Task: Generate issues/-/ISSUE.md — Defect-in-Shipped-Code Trigger

Task: Generate issues/<NNN>-<slug>/ISSUE.md — Defect-in-Shipped-Code Trigger

Objective

Produce one issues/<NNN>-<slug>/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/<area>/u<NN>/SPEC.md.
3. Existing issues (auto-discovered) — issues/*/ISSUE.md. Frontmatter scan only. Used for <NNN> 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/<NNN>-<slug>/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.