--- name: bartsoj/ISSUE.md source: https://app.decimal.ai/s/bartsoj-issue-md@1/SKILL.md source_sha256: 838b5cbabc62 --- # Task: Generate `issues/-/ISSUE.md` — Defect-in-Shipped-Code Trigger ## Objective Produce one `issues/-/ISSUE.md` file per invocation that files a single defect in shipped code as a durable, citable trigger artifact. The skill is one of two trigger-creation skills (the other is `/ROADMAP.md` for planned work); the `/ROADMAP.md` and `/ISSUE.md` artifacts are the only way work enters phase G of the Agent-Driven Development pipeline. The output carries enough to scope a fix unit at G1, validate scope at G2, verify the reproduction at G7, and feed orchestrator/reconcile lifecycle transitions at G8. Frontmatter is mutable — the orchestrator and `/RECONCILIATION.md` advance `status` (`open → in-progress → fixed`) and populate `promoted_to_units`, `fixed_in`, `fixed_date` over the issue's lifecycle. The body is largely write-once: regenerate only when the user explicitly asks to refine (typically to add a re-confirmation note when an issue resurfaces). ISSUE exists because every defect must originate from a durable artifact — not a chat message, not a Slack thread, not an inline TODO. Without it, fixes are filed against premises that disappear once the conversation that surfaced them ends, and `/VERIFICATION.md` (G7) has nothing to verify against. The defining discipline — and the commonest violation — is **issues describe shipped behavior that contradicts a documented expectation**: every issue must cite the source-of-truth artifact (`INTERFACES.md`, an IA, `BEHAVIOR.md`, a unit's `SPEC.md`, …) by `ARTIFACT§section`, and the skill MUST NOT fabricate expected behavior when the source-of-truth is silent. Silent source-of-truth is itself a finding — it gets surfaced and the issue is filed `status: open-for-discussion`. --- ## Inputs 1. **Defect intent** (required, primary subject) — free-text description of what's wrong. Includes (or implies) the symptom, the context where it was observed, the suspected component (when known), severity hint (when known), and reproduction steps (when known). The skill extracts these from the prose; missing fields surface as `Open Questions` or as conservative defaults. 2. **Source-of-truth artifacts** (auto-discovered, selective) — the artifact(s) that document the *expected* behavior the defect violates. Pick 1–3 based on the defect's surface: HTTP / wire-format → `INTERFACES.md`; UI → `WEB_IA.md` / `MOBILE_IA.md` / `TUI_IA.md`; CLI → `CLI_IA.md`; voice → `VOICE_IA.md`; state-machine / saga → `BEHAVIOR.md`; data integrity / persistence → `DATA.md`; error-message / error-code → `ERRORS.md`; domain-invariant → `DOMAIN.md`; security → `SECURITY.md`; performance / observability → `QUALITY.md`; ops / config / deployment → `OPERATIONS.md`; unit-level → the unit's `units//u/SPEC.md`. 3. **Existing issues** (auto-discovered) — `issues/*/ISSUE.md`. Frontmatter scan only. Used for `` allocation, duplicate detection, and related-issue cross-referencing. 4. **Existing units** (auto-discovered) — `units/*/u*/SPEC.md`. Frontmatter scan only. Used to identify the owning unit (via `files:` overlap with the suspected component) and populate `component:` and `References` accurately. 5. **Existing roadmap items** (auto-discovered) — `roadmap/*/ROADMAP.md`. Frontmatter scan only. Used to detect overlap with planned-but-unshipped work, which would make the report a roadmap item, not an issue. 6. **Codebase access** (optional) — for grepping the suspected file/function to confirm root cause when the defect intent points to a symptom but not a root cause. 7. **Existing `issues/-/ISSUE.md`** (auto-discovered — only if refining) — when the user asks to refine an existing issue, read it fully and **preserve orchestrator-managed frontmatter fields** (`id`, `status` transitions, `promoted_to_units`, `fixed_in`, `fixed_date`). Read budget: 1–3 source-of-truth artifacts + 2–4 frontmatter scans (cheap — YAML headers only) + 0–2 selective unit SPEC reads + codebase grep results. Within ADD's bounded read-set principle (≤ 10 reads). --- ## Workflow Issue filing proceeds in six phases: symptom extraction, source-of-truth verification, discovery, body authoring, ID allocation and frontmatter, and validation-and-write. Phases are sequential; revisit earlier phases if a later one reveals a missing source-of-truth, an undiscovered duplicate, or a contradiction. ### Phase 1: Symptom Extraction Read the defect intent end-to-end. Extract seven things into a working note: - **Symptom** — what is observed. The user-facing or system-facing failure, stated tightly. "POST /repos returns 500", "CLI exit code 0 but no repo created", "web modal shows raw JSON instead of formatted error." Becomes the seed for `title:` and `Summary`. - **Context** — where it was observed. "While running `syns init` in a fresh checkout", "during code review of u115", "in the system verification pass on 2026-05-08." Becomes the `discovered_in:` field. - **Severity hint** — `low` | `medium` | `medium-high` | `high`. Inferred from impact: - `high`: corrupts user data, breaks the public contract, leaks sensitive information, complete inability to use a primary feature. - `medium-high`: visible UX failure on a primary path with no workaround. - `medium`: visible failure with a workaround, OR a public-contract drift that nobody is currently relying on. - `low`: polish, missed affordance, internal-only inconsistency. When uncertain, pick conservatively (lower) and call out the uncertainty in `severity_note`. - **Component hint** — the code path or module suspected. May be precise (`apps/server/src/modules/repos/create.ts`) or fuzzy (`server, repo creation`). Resolve fuzzy hints by codebase grep in Phase 3 to produce a concrete path for `component:`. - **Kind** — `bug` (something is broken that has never worked correctly) or `regression` (something that previously worked is now broken). When the prose names a recent change ("after we landed u062"), prefer `regression`. When unstated and indeterminate, default to `bug` and surface the uncertainty in `Open Questions`. - **Reproduction steps** — when present, extract verbatim. When absent, surface in `Open Questions` ("Reproduction steps required — please add when next observed") and proceed. - **Expected behavior** — when stated by the user, capture. Otherwise the skill derives it from the source-of-truth artifact in Phase 2 (and only from there — never from imagination). ### Phase 2: Source-of-Truth Verification This is the load-bearing phase. The skill must verify that the defect actually contradicts a documented expectation. If the source-of-truth is silent on the defect's behavior, this is *not* a routine issue — it is either a missing-spec gap (file as roadmap refinement) or a defect in the spec itself. Either way, the skill does NOT invent expected behavior. Procedure: 1. Map the symptom to the source-of-truth artifact using the table in Inputs §2. 2. Read the relevant section of that artifact. Confirm it specifies the expected behavior. 3. Capture the citation by stable ID — `ARTIFACT§section` or `ARTIFACT/ID` (per ADD §7.2; never quote inline prose, quotes go stale on regeneration). 4. If the source-of-truth says nothing about this behavior: - Surface in `Open Questions`: "Source-of-truth `` does not specify behavior for this scenario. May be a missing-spec gap (file as a roadmap refinement?) rather than a defect." - Set `status: open-for-discussion` (Rule 1) — the framing is unsettled and the orchestrator should not pick this up for fix work without direction. - Pick severity conservatively. The skill MUST NEVER invent expected behavior. If the source-of-truth is silent, surface that fact rather than write expected behavior from imagination. ### Phase 3: Discovery — Duplicates, Related Issues, Owning Unit Phase 3 is mandatory. Concrete file operations: 1. **Duplicate check.** Glob `issues/*/ISSUE.md`. Read frontmatter (only) for each. If any has overlapping `component:` AND overlapping symptom (judged from `title`): - If the duplicate is `status: open` or `in-progress`: surface in `Open Questions` ("This may be a duplicate of `issues/-`. Recommend orchestrator disambiguates.") and DO NOT silently file. - If the duplicate is `status: fixed` and the defect is observed in current code: this is a **regression**. Set `kind: regression`, add the closed duplicate to `related:`, and proceed. 2. **Related-issue discovery.** Among non-duplicate hits with overlapping `component:`, list the most relevant 1–3 in `related:` and in the body's `References` section. Cite by `issues/-`. 3. **Owning-unit discovery.** Read frontmatter (only) of every `units/*/u*/SPEC.md`; find units whose `files:` overlaps with the suspected component. The most likely owning unit goes in `References`. If its files are clearly the root cause, name it in the body's `Root cause` section. Cite by `u`. 4. **Roadmap-overlap check.** Read frontmatter (only) of every `roadmap/*/ROADMAP.md`. If the defect's symptom corresponds to behavior in a roadmap item with `status: idea | planned | in-design | in-progress | partial`, the work hasn't shipped — this is not an issue, it is "the feature isn't built yet." Surface in `Open Questions` ("Symptom describes behavior in `roadmap/-` (status: planned); may not yet qualify as a defect.") and recommend the orchestrator file as roadmap (or close as duplicate of the existing roadmap item). Discovery output is **summarized, not exhaustive** — a tight bulleted list of relevant hits with stable-ID citations, each with a one-sentence relevance note. If discovery finds nothing: state that explicitly in `References` rather than omit the section. ### Phase 4: Body Authoring Author the body in fixed-order required sections (`Summary` → `Reproduction` → `Expected` → `Observed` → `Root cause` → `Scope / impact` → `Suggested fix` → `Alternatives considered` → `Open Questions` → `References`) plus conditional optional sections (`Workaround in place`, `Verification`, `Re-confirmation`, `Notes`, `Tests`) only when warranted (Rule 10). Section headings are mandatory and exact — downstream skills (`/SPEC.md` G1, `/VERIFICATION.md` G7) `grep` for them. The full template with placeholders is in Output Format below. While authoring, hold the line on Rule 1 (cite source-of-truth, do not invent expected behavior) and Rule 8 (suggested fix is a sketch, not a SPEC). The two largest temptations: writing `Expected` from imagination when the source-of-truth has no entry, and turning `Suggested fix` into a step-by-step plan. Both are downstream-skill territory paying rent in the wrong section. ### Phase 5: ID Allocation and Frontmatter **`` allocation.** Glob `issues/*/ISSUE.md`. Read frontmatter `id` for each. Take `max(id) + 1`. Zero-pad to 3 digits. Never reuse a retired id. Never go backwards. **Slug computation.** Kebab-case form of the `title` field — short, descriptive, ASCII letters/digits/hyphens only, lowercase. Filler words (`a`, `an`, `the`, `for`) stripped. Examples: - "POST /repos/{name}/push returns 200 but commit not persisted" → `push-200-commit-lost` - "syns clone exit code 0 even when clone fails" → `clone-exit-code-zero-on-fail` - "Role remove endpoint expects user_id but CLI sends username" → `role-remove-expects-user-id` The folder name `-`, the frontmatter `id`, and the slug used in citations must agree exactly. **Frontmatter — required fields at filing time:** ```yaml --- skill: ISSUE.md date: status: open | open-for-discussion id: "" title: kind: bug | regression severity: low | medium | medium-high | high severity_note: component: discovered: discovered_by: discovered_in: , system verification pass> promoted_to_units: [] related: [] --- ``` Notes: `status` enum is **deliberately overridden** to the lifecycle values `open | in-progress | fixed | deferred | wontfix | open-for-discussion` (per ADD §7.4); the skill emits only `open` or `open-for-discussion` at filing time, and the orchestrator advances `status` thereafter via the lifecycle bridge rules (ADD §7.7.1). `id` is **quoted** to preserve zero-padding (`"044"` ≠ `44`). `severity_note` is **required** (Rule 4). `promoted_to_units` is an **empty list at filing time**. `related` is populated from Phase 3 discovery. **Conditional fields** (`fixed_in`, `fixed_date`, `last_reconfirmed`, `last_reconfirmed_in`, `deferred_reason`, `deferred_date`, `wontfix_reason`) are either initialized as `null` at filing time or omitted entirely — be consistent within the file. The orchestrator and reconcile populate them later as the issue's lifecycle advances. ### Phase 6: Validation and Write Before writing the file, verify: - All required body sections (`Summary`, `Reproduction`, `Expected`, `Observed`, `Root cause`, `Scope / impact`, `References`, `Open Questions`) are present with their exact headings, in the fixed order. - `Reproduction` is concrete (numbered steps or copy-pasteable command sequence) — not "follow these steps", "sometimes fails", "occasionally produces", "randomly" (Rule 3). - `Expected` cites the source-of-truth by `ARTIFACT§section` or `ARTIFACT/ID` — never fabricates expected behavior (Rule 1). - `Observed` includes verbatim evidence — error message, HTTP response body, exit code, or path to a screenshot saved under `verification-evidence/`. - `severity_note` is present and is a sentence that justifies the chosen severity (Rule 4). - `component:` is a concrete code path, not a feature name (Rule 5). - No forbidden content per Rules 1, 3, 8, 10, 12 leaked anywhere. - Frontmatter `id` and the folder name `-` agree exactly. - The skill ran headless — no interactive prompts surfaced during execution. **Write.** Create the directory `issues/-/` (and the parent `issues/` if needed). Write `ISSUE.md` inside it. If the user supplied evidence artifacts (screenshots, captured HTTP traces, log files), save them under `issues/-/verification-evidence/` — keep evidence inside the issue's folder. Output to stdout a one-line confirmation with the file path and key fields: ``` Filed issues/057-push-200-commit-lost/ISSUE.md (kind=bug, severity=high, component=apps/server/src/modules/repos/push.ts). ``` --- ## Rules These rules govern the output document. Violations are detected by the Quality Checklist. ### 1. Issues describe shipped behavior that contradicts a source-of-truth Every issue must contradict a documented expectation. The `Expected` section MUST cite the source-of-truth artifact by `ARTIFACT§section` or `ARTIFACT/ID` — never fabricate expected behavior, never paraphrase prose, never guess. If the source-of-truth is silent on the defect's behavior, this is *not* a routine issue. It is either: - A missing-spec gap → surface in `Open Questions` and recommend filing a roadmap refinement instead. - A bug in the spec itself → surface and recommend updating the source-of-truth (which would be a different unit's work). Issues filed against silent source-of-truth must be flagged with `status: open-for-discussion` rather than `open`, indicating the framing is unsettled. The orchestrator does not pick up `open-for-discussion` issues for routine fix work without explicit direction. ### 2. One defect per file If two symptoms share a root cause, file ONE issue and describe both symptoms in `Summary`. If two root causes share a symptom, file TWO issues with reciprocal `related:` entries. Splitting genuinely-coupled symptoms into separate issues fragments the audit trail; combining genuinely-distinct root causes into one issue muddles tracking and verification. ### 3. Reproduction is concrete and copy-pasteable `Reproduction` is the test G7 runs against the fix. It must be unambiguous: - HTTP defects → exact `curl` command (or HTTP request method + path + headers + body). - CLI defects → exact invocation (`syns init --foo bar`). - UI defects → numbered steps a human follows ("1. Navigate to /repos. 2. Click 'New repository'. 3. Type 'foo' in the name field. 4. Click 'Create'. 5. Observe the modal does not close."). - State-machine defects → exact trigger sequence and the state transitions observed. Reject vague reproduction language: "sometimes fails", "occasionally produces", "randomly", "intermittently". If the defect is genuinely intermittent, describe the conditions that affect frequency (load, time-of-day, concurrent users, dataset size) and surface the residual unknowns in `Open Questions`. Frequency vagueness is the single most common reason a fix lands and the issue silently re-opens. ### 4. Severity has a justification `severity_note` (one sentence) is REQUIRED. It states *why* this severity. Without it, the rating is uninterrogable and triage cannot rank. Examples: - `severity: high`, `severity_note: "Corrupts user data: a successful POST returns 200 but the data is lost on next read."` - `severity: medium-high`, `severity_note: "Login flow is broken with no workaround on mobile Safari; iOS users cannot sign in."` - `severity: medium`, `severity_note: "Public-contract drift — response includes an extra field not documented; no current consumer reads it."` - `severity: low`, `severity_note: "Cosmetic — error message wording differs from the design system's error-message library."` When uncertainty about severity exists (e.g., possible data-corruption risk that has not been confirmed), pick conservatively (lower) and flag the uncertainty in `severity_note` and `Open Questions` simultaneously. ### 5. Component is a code path, not a feature name `component:` names files or directories where the defect lives, not features. `apps/server/src/modules/teams` is good. `team management` is not. Multi-path is fine when a defect spans paths: `"apps/server/src/modules/teams, apps/web/src/pages/teams"`. When the defect intent gives a fuzzy hint ("server, repo creation"), the skill grep-resolves it to a concrete path during Phase 3 before writing the field. If grep cannot resolve the hint, surface in `Open Questions` and write the closest concrete approximation (e.g., the module directory). ### 6. Discovery must be performed and reflected Phase 3 discovery is mandatory. The skill must: - Glob existing issues for duplicates and related entries. - Frontmatter-scan `units/*/u*/SPEC.md` to identify the owning unit. - Frontmatter-scan `roadmap/*/ROADMAP.md` to detect overlap with planned work. If discovery surfaces a likely duplicate, the new issue does NOT silently file — the skill flags it in `Open Questions` with the duplicate's id and recommends the orchestrator disambiguate. Discovery findings populate `related:` and the body's `References` section; if discovery finds nothing relevant, `References` says so explicitly rather than being omitted. ### 7. Issues are filed against shipped code, not against planned work If the defect's symptom corresponds to behavior that's still on the roadmap (not yet implemented), this is **not** an issue. The "defect" is "the feature isn't built yet" — which a roadmap item already covers, or a new roadmap item should. Concrete check: if the suspected component is named in a roadmap item with `status: idea | planned | in-design | in-progress | partial`, the work hasn't shipped. Flag in `Open Questions` and recommend the orchestrator file as roadmap (or close as duplicate of the existing roadmap item). ### 8. Suggested fix is a sketch, not a SPEC `Suggested fix`, when included, names specific files or contract changes — at the level of "in `apps/server/src/modules/repos/create.ts:34`, the validation regex must accept uppercase letters". It is **not** a full plan; that is `PLAN.md` territory if the fix is promoted to a unit. Keep it tight: a paragraph or a bulleted list of three-to-five concrete changes. If the fix has multiple plausible approaches, document the rejected ones in `Alternatives considered` with one-line rationale per alternative. If only one obvious approach exists, omit the `Alternatives considered` section entirely. If no fix is known, omit `Suggested fix` entirely. An empty section is worse than a missing one. ### 9. Citations by stable ID Cite the source-of-truth and related artifacts by stable ID: - `ARTIFACT§section` or `ARTIFACT/ID` for top-level design artifacts. - `issues/-` for related issues. - `roadmap/-` for related roadmap items. - `u` for related units. - `EP-name` for endpoints, `EVT-name` for events, `ERR_CODE` for error codes, `SM-...` / `SAGA-...` for state machines and sagas, `THREAT-NN` / `MIT-NN` for security, `INV-NN` for invariants, `UC-NN` for use cases. Never quote artifact prose inline — quotes go stale on regeneration. Reference, do not paraphrase. ### 10. Optional sections are included only when warranted Required sections (`Summary`, `Reproduction`, `Expected`, `Observed`, `Root cause`, `Scope / impact`, `References`, `Open Questions`) are always present. If genuinely empty (`Open Questions` resolved at filing time, for instance), state "All questions resolved." or the standard empty-state phrase. `Root cause` is required when known; when unknown, the heading IS present with the body "Root cause undetermined — see Open Questions for investigation needed." `Suggested fix` and `Alternatives considered` are conditional — if not applicable, omit the entire section heading. Optional sections (`Workaround in place`, `Verification`, `Re-confirmation`, `Notes`, `Tests`) are included only when warranted. Do NOT stub them empty. The standard empty-state ("None.") is reserved for required sections. ### 11. Single YAML frontmatter block One YAML frontmatter block at the top of the file. Never emit a second YAML block anywhere. Conditional fields (`fixed_*`, `deferred_*`, `wontfix_*`, `last_reconfirmed_*`) are either initialized as `null` at filing time or omitted entirely; the orchestrator populates them later. Be consistent within the file — do not mix the two styles. ### 12. Precision over vagueness No "appropriate", "relevant", "as needed", "etc.", "various", "and so on", "many", "some", "a few", "best practice", "industry-standard", "sometimes", "occasionally", "randomly", "intermittently" (without conditions). Use exact paths, exact codes, exact identifiers, exact response bodies. If exact is impossible because the cause is genuinely uncertain, surface it in `Open Questions` rather than hide behind a placeholder word. ### 13. No interactive questions The skill runs headless from `claude -p`. Never pause to ask the user. If a decision has one clearly correct answer, resolve silently. If genuinely ambiguous, surface in `Open Questions` with options, tradeoffs, and a recommendation. Common ambiguities for issues: - Suspected duplicate of an existing issue. - Source-of-truth silent on the defect's behavior. - Severity uncertain (write `severity_note` flagging the uncertainty and pick conservatively). - Reproduction not yet captured ("Reproduction steps required — please add when next observed"). - Bug vs regression unclear (default to `bug`, surface in `Open Questions`). --- ## Output Format The output is `issues/-/ISSUE.md`. The frontmatter is identical regardless of issue kind; the body uses required sections in fixed order plus conditional and optional sections. For two complete worked examples (a contract-mismatch bug and a CLI exit-code regression), see [`references/examples.md`](references/examples.md). ### Frontmatter ```yaml --- skill: ISSUE.md date: {YYYY-MM-DD} status: {open | open-for-discussion} id: "{NNN}" title: {one-line statement of what is wrong} kind: {bug | regression} severity: {low | medium | medium-high | high} severity_note: {one-sentence justification of why this severity} component: {code-path-or-paths} discovered: {YYYY-MM-DD} discovered_by: {handle} discovered_in: {short context — session, fix-batch, code review of u, system verification pass} promoted_to_units: [] related: [{issues/- | u | roadmap/-}, ...] # Conditional fields — initialized null at filing time; orchestrator/reconcile populates later fixed_in: null fixed_date: null last_reconfirmed: null last_reconfirmed_in: null deferred_reason: null deferred_date: null wontfix_reason: null --- ``` ### Body The body template below is wrapped in a 4-backtick fence so that the inner 3-backtick block (the verbatim-evidence block in `## Observed`) renders correctly. The issue file itself uses standard 3-backtick fences. ````markdown # ISSUE — {title} ## Summary {One paragraph: what's wrong, what's the user-facing or system-facing effect, where it's rooted. Often the title plus 2–3 sentences of elaboration.} ## Reproduction {Numbered steps or a copy-pasteable command sequence. Include exact inputs. For HTTP: include the curl command or the HTTP request. For CLI: include the exact invocation. For UI: numbered human-followable steps. For state machines: the exact trigger sequence and observed transitions.} 1. {Step} 2. {Step} 3. {Step} (Never "sometimes", "occasionally", "randomly". If frequency varies, describe the conditions that affect it.) ## Expected {What the source-of-truth document says should happen. Cite by stable ID; do not paraphrase or quote inline prose.} Per `{ARTIFACT§section}` or `{ARTIFACT/ID}`, {one-line statement of expected behavior}. ## Observed {What actually happens. Verbatim error messages, HTTP response bodies, exit codes, or paths to screenshots. Trim large blobs to the relevant excerpts; large artifacts go in a sibling `verification-evidence/` directory.} ``` {verbatim error or HTTP response or stack trace} ``` ## Root cause {When known: the line, function, or design contradiction responsible. Cite specific code paths. Example: "In `apps/server/src/modules/repos/create.ts:34`, the validation regex `/^[a-z0-9-]+$/` rejects uppercase letters, but the rename path at `apps/server/src/modules/repos/rename.ts:18` accepts them — the contract is not enforced consistently." When the root cause is a contradiction between two artifacts, name both. When unknown, write: "Root cause undetermined — see Open Questions for investigation needed."} ## Scope / impact - **Affected:** {who — actor names, deployments, regions} - **Frequency:** {one-line — "every request", "100% under sustained load", "only when X"} - **Workaround:** {one-line — "none", "users can ...", "can be avoided by ..."} ## Suggested fix {Conditional — Rule 8. When known: specific file paths, function names, or contract changes. Not a full plan — that lives in PLAN.md if the fix is promoted to a unit. Paragraph or tight bulleted list. Skip this entire section if no plausible fix is known.} ## Alternatives considered {Conditional — when the suggested fix has plausible competitors, document the rejected ones and why. Skip this entire section when there is only one obvious approach or no suggested fix is offered.} - **{Alternative A}** — {description, why rejected}. ## Open Questions - [ ] {Question — e.g., "Is this a duplicate of `issues/044-...`?", "Source-of-truth silent on this scenario; should we update INTERFACES first?", "Severity uncertain — possibly higher if data-corruption risk confirmed."} - **Option A:** {description} — {tradeoff} - **Option B:** {description} — {tradeoff} - **Recommendation:** {suggestion and reasoning} (If none: "All questions resolved.") ## References - `{ARTIFACT§section}` — source-of-truth for the expected behavior. - `{u}` — owning unit (likely shipped the defective code). - `{issues/-}` — related issue. - `{URL}` — external reference (vendor docs, CVE, RFC). ```` ### Optional sections (include only when warranted — Rule 10) ```markdown ## Workaround in place {When a workaround exists in code or operations — describe it. Often added later, after a workaround is deployed while the root fix is being designed.} ## Verification {Added after the issue is fixed — evidence that the fix works. Reproduction steps now produce expected behavior. Cite the unit that fixed it: `u`, date `YYYY-MM-DD`. Typically written by the orchestrator at G7 verification, not at filing time.} ## Re-confirmation — {event} {date} {Added when an existing issue is reconfirmed without being fixed (the issue re-surfaced after a separate change, or an old issue is observed again in testing). The body grows; the file is not regenerated. The frontmatter fields `last_reconfirmed` and `last_reconfirmed_in` are also updated.} ## Notes {Free-form context that does not fit elsewhere — historical commentary, related-but-tangential observations.} ## Tests {Links to existing failing tests, or notes about tests to add as part of the fix. Often empty at filing; populated when the fix is implemented.} ``` --- ## Scope ### In scope - Extracting symptom, context, severity, component, kind, and reproduction from defect intent. - Verifying the defect against the source-of-truth artifact and citing it by stable ID — never fabricating expected behavior. - Discovery: globbing existing issues for duplicates, frontmatter-scanning units for the owning unit, frontmatter-scanning roadmap for planned-but-unshipped overlap. - Allocating the next `` from existing issues; computing the slug from the title. - Creating the directory `issues/-/` and writing `ISSUE.md` inside it. - Authoring required body sections in the fixed order; including optional sections only when warranted. - Populating frontmatter completely with `severity_note` justifying severity (Rule 4). - Surfacing unresolved questions in `Open Questions` rather than guessing silently. - Saving user-supplied evidence (screenshots, HTTP traces, log files) under `issues/-/verification-evidence/`. - Preserving orchestrator-managed frontmatter (`id`, `status`, `promoted_to_units`, `fixed_*`, `last_reconfirmed_*`) when refining an existing issue. ### Out of scope - Resolving the defect — that is a unit running phase G (G1–G8) under `units//u/`. - Filing planned work — owned by `/ROADMAP.md` (sibling skill; `roadmap/-/ROADMAP.md`). - Resolving open questions — owned by `/DECISION.md` (cross-cutting; `decisions/D-NNN-slug/DECISION.md`). - Picking up the issue to fix it — owned by the orchestrator (it allocates a unit and runs G1–G8). - Producing the SPEC for the fix — owned by `/SPEC.md` (G1; reads this issue as a trigger via `trigger.issues`). - Producing the PLAN, IMPLEMENTATION, CODE_REVIEW, VERIFICATION, RECONCILIATION for the fix — owned by `/PLAN.md`, `/IMPLEMENTATION.md`, `/CODE_REVIEW.md`, `/VERIFICATION.md`, `/RECONCILIATION.md` respectively. - Editing top-level design artifacts (DOMAIN, INTERFACES, DATA, BEHAVIOR, etc.) — owned by their own skills (`/DOMAIN.md`, `/INTERFACES.md`, etc.) and applied by `/RECONCILIATION.md` (G8). - Status transitions on the issue after filing (`open` → `in-progress` → `fixed`) — performed by the orchestrator and `/RECONCILIATION.md` per ADD §7.7.1 trigger lifecycle bridge rules. - Wire formats, database schemas, function signatures, code, step-by-step plans — owned by SPEC, INTERFACES (via reconcile), DATA (via reconcile), IMPLEMENTATION, and PLAN respectively. --- ## Quality Checklist Before considering the issue file complete, verify: - [ ] Output file has valid YAML frontmatter with all required fields (`skill: ISSUE.md`, `date`, `status`, `id`, `title`, `kind`, `severity`, `severity_note`, `component`, `discovered`, `discovered_by`, `discovered_in`, `promoted_to_units`, `related`) - [ ] Single YAML frontmatter block at the top — never two - [ ] No placeholders, TODOs, or vague language ("appropriate", "relevant", "as needed", "etc.", "various", "and so on", "many", "some", "best practice", "industry-standard", "sometimes", "occasionally", "randomly") - [ ] Frontmatter `id` and the folder name `-` agree exactly - [ ] `id` is quoted in frontmatter (preserves zero-padding: `"044"` not `44`) - [ ] `kind` is one of `bug | regression` - [ ] `severity` is one of `low | medium | medium-high | high` - [ ] `severity_note` is present and is a sentence justifying the chosen severity (Rule 4) - [ ] `component` is a concrete code path (or comma-separated paths), not a feature name (Rule 5) - [ ] `status` is `open` for newly-filed issues, or `open-for-discussion` if framing is unsettled (source-of-truth silent — Rule 1) - [ ] `promoted_to_units` is an empty list (`[]`) at filing time — orchestrator populates later - [ ] All required body sections (`Summary`, `Reproduction`, `Expected`, `Observed`, `Root cause`, `Scope / impact`, `References`, `Open Questions`) are present with their exact headings, in the fixed order - [ ] `Reproduction` is concrete (numbered steps or copy-pasteable command), not vague language (Rule 3) - [ ] `Expected` cites the source-of-truth by `ARTIFACT§section` or `ARTIFACT/ID` — never fabricates expected behavior (Rule 1) - [ ] `Observed` includes verbatim evidence (error message, HTTP response, exit code, or screenshot path) - [ ] `Root cause` is present with either the actual root cause (citing code paths) or the explicit "undetermined — see Open Questions" (Rule 10) - [ ] `Scope / impact` lists affected actors, frequency, and workaround presence - [ ] `Suggested fix` is included when a fix is known, omitted otherwise (no empty section — Rule 10) - [ ] `Alternatives considered` is included when the suggested fix has competitors, omitted otherwise (Rule 10) - [ ] Optional sections (`Workaround in place`, `Verification`, `Re-confirmation`, `Notes`, `Tests`) are included only when warranted; not stubbed empty - [ ] If discovery surfaced a likely duplicate, it is flagged in `Open Questions` (not filed silently — Rule 6) - [ ] If the source-of-truth is silent on the defect's behavior, it is flagged in `Open Questions` AND `status` is `open-for-discussion` (Rule 1) - [ ] If the symptom describes still-planned roadmap work, it is flagged in `Open Questions` (Rule 7) - [ ] Citations use stable IDs (`ARTIFACT§section`, `EP-name`, `EVT-name`, `ERR_CODE`, `SM-name`, `SAGA-name`, `INV-NN`, `UC-NN`, `u`, `issues/-`, `roadmap/-`) — never quoted artifact prose (Rule 9) - [ ] No interactive questions surfaced during execution — the skill ran headless from start to finish - [ ] User-supplied evidence (screenshots, HTTP traces, log files) is saved under `issues/-/verification-evidence/` - [ ] Output is self-contained — readable and actionable without opening other files - [ ] Document length is 80–400 lines; overflow indicates two-issues-in-one (split per Rule 2) or speculation creeping in (trim)