description: After root cause analysis, classify the defect and route accordingly. Most bugs are code defects — the default is to continue. Escalation is the exception, not the rule.
5.1 Classify the defect
classification:
fix_here:
- type: Code defect
signal: Design is correct, code is wrong. Contract holds, implementation doesn't match.
examples: [wrong conditional, off-by-one, missing null check, misused API, stale cache, race condition]
- type: Missing edge case
signal: Happy path works, valid input or state not handled. Design accounts for it or should trivially.
examples: [unhandled error code, missing boundary validation, timeout not set]
- type: Regression
signal: Previously working code broken by recent change. Design didn't change, implementation drifted.
examples: [refactor broke a caller, dependency update changed behavior]
- type: Test gap
signal: Behavior is wrong but no test covers it. Fix is code + test.
examples: [untested branch, missing integration test]
- type: Dependency-induced
signal: Library or platform behaves differently than expected. Fix is adapting our code, not redesigning.
examples: [API deprecation, version incompatibility, platform quirk]
escalate:
- type: Solve-level flaw
signal: Internal subsystem design is wrong. Arch contract is fine, but subsystem can't deliver it with current internal structure.
examples: [wrong data model, wrong algorithm choice, abstraction that can't handle actual data shape]
route: /solve
- type: Arch-level flaw
signal: Macro decomposition is wrong. Wrong contract, wrong subsystem boundary, or constraint that can't hold.
examples: [subsystem needs data it has no contract to receive, circular dependency, physically impossible constraint]
route: /arch
The bar for escalation is high. If the root cause can be fixed by changing code within the existing design — even if the fix is ugly, even if it reveals a test gap, even if it touches multiple files — it's a code defect. Escalate only when a code fix would be a patch over a structural problem that will recur.
If code defect (including edge cases, regressions, test gaps, dependency issues): Proceed to Task 6.
If solve-level flaw:
- Expand the ticket's Root Cause section with the design findings — what's wrong with the internal design, what needs to change, and why a code fix won't hold. The ticket becomes the
/solve brief.
- Update the ticket status to
escalated in PROCESS_DOCS/tickets/manifest.yaml
- Tell the user: "Root cause is a design flaw in [subsystem]. Ticket expanded as a
/solve brief."
- Stop — do not proceed to Task 6.
If arch-level flaw:
- Update the arch manifest (
PROCESS_DOCS/arch/[project].manifest.yaml) — add notes to the affected subsystem describing the finding
- Expand the ticket's Root Cause section with the architectural finding
- Update the ticket status to
escalated in PROCESS_DOCS/tickets/manifest.yaml
- Tell the user: "Root cause is an architecture-level flaw in [subsystem]. Arch manifest updated. This needs
/arch."
- Stop — do not proceed to Task 6.
