uniffy-io/uniffy / .agents/skills/uniffy-issue
uniffy-issue
VerifiedCreate or refine GitHub issues in `uniffy-io/uniffy` using the project's title, template, dependency, project, and image-attachment conventions. Use when asked to create, open, file, draft, report, rename, or track a bug, feature, security issue, or performance issue in this repository, including requests that begin with `[BUG]`, `[FEATURE]`, `[SECURITY]`, or `[PERFORMANCE]`. Skip for pull requests, commit messages, implementation plans that do not need a tracking issue, other repositories, or general GitHub CLI questions.
Uniffy Issue Creation
Codifies the issue conventions for the uniffy-io/uniffy repo. Apply every time you draft, refine, or post an issue.
Title format
[TYPE] Domain: short description
TYPEis one ofBUG,FEATURE,SECURITY,PERFORMANCE.Domainis CamelCase, named after the vertical slice (backendsrc/uniffy/domains/<x>/and frontendsrc/ui/src/features/<x>/share the name). Omit theDomain:segment only if the change is genuinely cross-cutting with no dominant domain.- Keep titles under ~80 chars. Detail goes in the body, not the title.
Examples:
[BUG] Agents: cannot read images sent in chat[FEATURE] Chat: app-wide messenger dock[FEATURE] Agents: rooms domain tools
Templates
Four issue forms live in .github/ISSUE_TEMPLATE/:
| File | Use for |
|---|---|
bug.yml | Defects in existing functionality |
feature.yml | New functionality or significant enhancement |
security.yml | Hardening, audit findings, dependency CVEs (NOT active exploits - those email admins@uniffy.io) |
performance.yml | Slowness, high resource use, scalability |
When creating via gh issue create --body, write the body in the shape the matching template expects (same section headings + order). When the user files via the web UI, the template renders automatically.
Labels
None. Issues in this repo carry no labels: the title prefix carries the type and domain, and the Area body section carries the areas. Do not add labels even though domain:* and area:* labels still exist in the repo.
Body sections (FEATURE template - the gold standard)
## Summary
One paragraph. What and why in one breath. No fluff.
## Motivation
User need, business driver, technical gap. The "so what".
## User Story
As a <role>, I want <capability> so that <outcome>.
## Scope
In:
- bullet of every behaviour the change must produce
- include concrete file paths and module names when known
- include acceptance-checkable items
Out:
- explicit non-goals (deferred to v2, separate issue, won't fix)
- prevents scope creep during execution
## Acceptance Criteria
- [ ] each criterion phrased as a verifiable check
- [ ] every Scope-In bullet should produce at least one box
- [ ] include tests, migrations, docs updates, telemetry as boxes
- [ ] always include rule-driven boxes that apply to the change
## Area
backend / frontend / mobile / proto / infra
## Alternatives Considered
- **Option name.** One-line description. Rejected: reason.
- Three to five alternatives is typical. Show the road not taken.
## Additional Notes - First-Glance Pointers
Where the change lands in the codebase. File paths, class names, line numbers.
Hidden constraints, performance bars (see backend rules' Performance-Critical
Domains for chat/agents), prerequisite refactors.
For BUG: replace Motivation/Scope/Acceptance with Steps to Reproduce / Expected / Actual / Severity / Environment. For SECURITY: Category / Severity / Impact / Reproduction-or-Evidence / Suggested Mitigation / References. For PERFORMANCE: Current Measurement (numbers + how measured) / Target (threshold + why) / Reproduction / Profiling Evidence / Suspected Cause.
Pre-creation recon (mandatory for non-trivial issues)
Before writing the body, do enough recon to make "Additional Notes - First-Glance Pointers" accurate. Verify the gap is real:
- Search the affected domain with
rgandrg --filesto confirm the claimed missing behaviour really is missing - never assert "code does not handle X" without searching. - Read the key files referenced in the body. Cite
file_path:line_number. - Cross-check
.agents/rules/<domain>.mdfor established patterns. - Check
.agents/local/plans/backlogs/and any available project memory for relevant state, prior decisions, or feedback rules.
If the user says "first analyse" or "don't create yet", deliver findings as a regular response and wait for the go-ahead. Otherwise proceed to create after recon.
Creating via gh CLI
gh issue create \
--title "[FEATURE] Domain: title" \
--body "$(cat <<'EOF'
## Summary
...
EOF
)"
After creation, capture the issue number from the URL output. Then:
-
Link blockers via GraphQL (gh CLI has no native flag):
# Get node ids gh api graphql -f query='query { repository(owner:"uniffy-io", name:"uniffy") { issue(number:<blocked>) { id } } }' --jq '.data.repository.issue.id' gh api graphql -f query='query { repository(owner:"uniffy-io", name:"uniffy") { issue(number:<blocker>) { id } } }' --jq '.data.repository.issue.id' # Create the dependency gh api graphql -f query='mutation { addBlockedBy(input: { issueId: "<blocked-id>", blockingIssueId: "<blocker-id>" }) { issue { number } } }'Use the native dependency, NOT a plain comment or markdown link. The dependency shows in the sidebar and filters like
is:open is:issue -blocked:*. -
If the user wants an image attached:
ghCLI cannot upload binary attachments. Two paths:- Default: create the issue without the image, tell the user to drag-drop it into the issue in the browser, and preserve its temporary path for handoff.
- Persistent: commit the image to a tracked location and reference via raw URL. Only with explicit user OK - polluting the repo for an issue asset is rarely worth it.
Style and content rules
Apply AGENTS.md, the relevant .agents/rules/, and these issue-specific conventions when drafting body text:
- No emojis anywhere. Not in titles, bodies, commit messages, or PR descriptions.
- Single hyphens only. Never use em dashes or double hyphens; use
-or a comma to separate clauses. - Cite file:line for "where this lands" pointers. Never invent paths. If you cannot verify, say "look around
domains/<x>/" instead of fabricating a specific file. - No comments-style narration. Body sections describe the work, not the conversation that led to it. Do not write "as discussed", "per the user", "from our chat earlier".
- Acceptance Criteria boxes must be verifiable. "Works correctly" is not a criterion. "
SUM(token_estimate)query returns under 50ms p95 on 100k-row session" is. - Honor explicit compatibility direction. If the current instructions rule out backward compatibility and the issue introduces a breaking shape, scope it as "update all call sites", not "add a compatibility shim".
- Rules-driven boxes: when an issue touches a domain with rules in
.agents/rules/<x>.md, fold the relevant rules into the acceptance criteria so they cannot be forgotten in implementation. Examples: chat changes must keep hot reads through Valkey caches; agents changes must populatetoken_estimateat INSERT; UI changes must use the theme system + responsive breakpoints +useDocumentTitle.
Renaming existing issues
When asked to rename to follow the convention:
gh issue edit <num> --title "[TYPE] Domain: new title"
Apply the title convention above to both issues and PRs.
Working backwards from a screenshot
If the user shares a screenshot showing a bug or feature request:
- Inspect the image with the available image viewer.
- Recon the relevant code path.
- Draft the body with concrete pointers.
- Create the issue.
- Tell the user how to attach the image (gh limitation).
Defaults summary
| Field | Default |
|---|---|
| Repo | uniffy-io/uniffy |
| Project | V1 Roadmap (org project number 3, owner uniffy-io). New issues join it automatically; never run item-add. Effort lives there as Size (XS to XL) and Estimate (working days), set only when asked |
| Native dependency | Use addBlockedBy GraphQL when one issue blocks another |
| Image attach | Tell user to drag-drop in browser (gh limitation) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |