---

Status: complete Last updated: 2026-04-30 Parent: Design - Architecture Overview Read before this: Design - Architecture Overview, Contract - Phase Outcome

Issues As Durable Record

Current state

Each feature lives as a single issue on the active forge. The issue's status — usually a label, sometimes a project board column — reflects pipeline position: requirements → planning → developing → qa → integrating → uat → deployed → pending-docs.

The issue body holds the PREQ. Comments accumulate chronologically as work progresses:

• The SREQ (after technical planning approval, merged with the plan)
• A Phase Outcome per skill run
• Dev journals — one per work unit
• Validation journals — one per QA domain run
• QA reports — one per domain per /qa-fix invocation
• Decision resolutions, referencing decision IDs from the relevant Phase Outcome
• General discussion (clarifications, approvals)
• Closeout deliverables (traceability matrix, learning report)

Work units (WU-N) are /develop's runtime decomposition and don't map to issues.

The only legitimate fork from the single-issue model is a deferred QA finding. When the orchestrator decides not to fix a finding before release (a Pending Decision in the QA Phase Outcome), the new issue is spawned, linked back to the parent, and goes onto the backlog with its own priority. The parent's QA report comment notes "Finding X deferred — see issue #N." The dev agent never makes this decision unilaterally.

Rationale

Issues are the durable record because they give the system five things at once: multi-agent visibility (other systems can read state), process visibility (the dashboard sees pipeline position at a glance), stakeholder review through a familiar UI, cross-container handoff when work splits, and a learning archive (journals accumulate as raw material for cross-feature analysis).

The single-issue model replaced an earlier multi-issue model (parent issue + one child per SREQ + one child per QA domain) because that model encoded a parallelism that doesn't exist in practice. QA findings block the parent feature by default — there's no QA pipeline running independently of the feature pipeline; they're the same lifecycle expressed twice. Two issues for one state machine is bookkeeping overhead, especially when the consumer is mostly an agent that paginates fine through a long comment thread.

The deferred-finding fork survives because that is a real lifecycle separation — once deferred, the finding goes onto a backlog with its own priority and may take months to resolve. That's a different lifecycle from "this feature, right now."

The system is not designed for code-level debugging. Git history and PRs cover that. Issues serve as the long-term answer to "why does the system do X" — the PREQ explains what was wanted, the SREQ explains the approach, the dev journals capture what actually happened, and the closeout summarises.

Open questions

None.