Pssah4 Digital Innovation Agents Coding

Coding -- Review, Handoff & Living Documents

This skill has two entry conditions:

1. Implementation entry (the typical case): a FEATURE / IMP / ADR / FIX is ready to be built. The full review-implement-writeback flow below applies.
2. Bug-capture entry (no implementation required): the user reports a bug outside of an active implementation run. The skill captures the FIX artefact (BACKLOG row + FIX detail file + branch) and lets the user decide whether to implement now or later. See "Bug-capture entry point" in MANDATORY Phase 0 below.

The triggers in the description ("implement", "code", "build feature") cover case 1. Phrases like "Bug X", "Fix gefunden", "es gibt einen Fehler in FEAT-..." cover case 2.

MANDATORY Pre-Phase 0: Branch and item check

Coding implements a specific FEAT / FIX / IMP from the backlog. Run the team-workflow check (full rules: skills/project-conventions/references/team-workflow.md):

1. Identify the active item. For mid-cycle FIX or IMP discovered during coding, write the BACKLOG row first.

2. Verify the branch matches feature/<item-id-lower>-<slug> (or fix/... / chore/...). On a wrong branch, AskUserQuestion to switch.

3. Skill-triggered GitHub integration:

   python3 tools/github-integration/flow.py create-issue --item <ID>
   python3 tools/github-integration/flow.py open-draft-pr --item <ID>
   

4. At Handoff Ritual end, tag the phase:

   python3 tools/github-integration/flow.py tag-phase --item <ID> --phase code
   

5. Write .git/dia-active-skill so subsequent invocations stay silent.

MANDATORY Phase 0: Artifact triage

Before any code, doc, or spec change, the skill determines which artifact category the work falls into:

1. New FEATURE (user-facing capability that did not exist before).
2. IMPROVEMENT (IMP) on an existing feature (refactor, performance, doc drift, tests, config).
3. FIX for a bug or drift on an existing feature.
4. ADR when the work is an architecture decision.

Rule: if the assignment cannot be derived unambiguously from the user prompt, the skill asks one short question before anything else (in the user's working language; the English wording below is a template):

"Is this a new feature, an improvement on an existing feature, or a fix for a bug? If feature or IMP/FIX: which feature and which epic?"

No code or spec change without this assignment. FIX and IMP require feature: and epic: in the frontmatter. Details on the decision tree and exceptions live in skills/project-conventions/references/graph-invariants.md (section "Artifact triage at entry point").

Bug-capture entry point (no implementation required)

/coding is also the entry point when the user reports a bug outside of an active implementation run ("ich habe einen Bug in Feature X gefunden", "Login bricht ab"). The skill MUST be able to capture the bug without forcing the user into an immediate fix. Flow:

1. Run the same Phase 0 triage. The user's prompt usually maps to FIX.
2. Identify the affected FEAT-{ee}-{ff} (ask if unclear).
3. Write the BACKLOG row first (status Ready, phase Building, priority from the user, Source BUG).
4. Create the detail file at _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md from templates/FIX-TEMPLATE.md. Fill Symptom and what is currently known about the cause; leave Fix and Regression test empty.
5. Run the phase-end commit (per team-workflow.md) with message chore(fix): FIX-{ee}-{ff}-{nn} bug captured. The commit creates the fix/<id-lower>-<slug> branch via the commit-boundary check.
6. Ask the user: "Bug erfasst. Soll ich jetzt den Fix implementieren (/coding Phase 1+ auf diesem Branch), oder reicht die Erfassung fuer jetzt?"

If the user picks "nur erfassen", the skill ends after the commit and the bug waits in the backlog as a regular FIX item. The next /coding invocation on that FIX-ID resumes from Phase 1.

The capture path is identical to the in-flight Mid-course bug discovery trigger (Phase 4b later in this file), only the entry condition differs. Both converge on the same artefact shape: BACKLOG row + FIX detail file + branch.

Hotfix lane (fix-now, document-after)

Some bugs are obvious and small enough that the standard capture-then-fix path adds friction without adding value. The hotfix lane lets /coding fix immediately, then create the FIX-Row and GitHub issue afterwards so the work is still visible in the backlog and on the team board.

The hotfix lane is allowed only when all five criteria hold:

1. The fix touches at most three files.
2. No new feature, no new dependency.
3. No breaking change to a public API or interface.
4. The fix takes under 15 minutes.
5. An existing FEAT covers the affected functionality, so the FIX has a clear parent to attach to.

If any single criterion fails, fall back to the standard bug-capture flow (FIX-Row first, fix later).

When all five criteria hold, the flow is:

1. Fix immediately. /coding analyses, fixes, and runs the relevant tests in place. No FIX-Row yet.
2. Document right after the fix lands locally (binding):
   • Write the BACKLOG row for the FIX (status Ready or In Progress depending on whether the commit already exists, phase Building, Source BUG, Refs the parent FEAT).
   • Create the FIX detail file under _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md.
   • Commit with the canonical message fix: FIX-{ee}-{ff}-{nn} <short description> and the standard Refs: trailer.
   • When mode = "github-sync": create the matching GitHub issue (gh issue create --title "FIX-{ee}-{ff}-{nn}: {slug}" --label "fix,hotfix"), then run python3 tools/github-integration/flow.py sync-status --item FIX-{ee}-{ff}-{nn}.
   • Always (in any mode) close with python3 tools/github-integration/flow.py validate-fix --item FIX-{ee}-{ff}-{nn} to run the hotfix-scoped consistency check described below.
3. Acknowledge in chat: list the modified files, the FIX-ID, the issue URL (if created), and the validate-fix verdict.

The hotfix lane does not suspend the regression-test cycle (Phase 4b). If the bug is non-trivial enough to need a regression test, write it; the 15-minute budget includes the test.

Four consistency mechanisms keep the hotfix lane safe even when the V-Model phases are skipped:

1. FIX-Row in BACKLOG.md (mandatory, even retroactively). Every fix gets a BACKLOG row with full ID FIX-{ee}-{ff}-{nn}, either before the fix (standard lane) or right after (hotfix lane). The row is the anchor that /consistency-check mode A uses to find and validate the fix.
2. Commit cites the FIX-ID. The commit message subject and Refs: trailer both name the FIX, the parent FEAT, and any other affected artifact:

   fix: FIX-05-02-01 button click handler null check
   
   Refs: FIX-05-02-01, FEAT-05-02
   

   Git history and BACKLOG.md stay synchronized through the cite.
3. Deferred-stub marker (bidirectional binding). If the fix leaves a temporary stub, /consistency-check mode A enforces the link in both directions:
   • code marker // FIXME(stub): <reason> -- see FIX-05-02-01
   • the FIX row points back at the stub via the Notes column A missing pair triggers stub-without-fix-row or fix-without-stub-evidence.
4. Regression-test cycle. Hotfixes still run the Phase 4b 3-run cycle (write test, run passes, revert fix run fails, restore fix run passes). The FIX detail file gets a ## Regression test entry confirming the cycle.

The gap. /consistency-check mode A normally fires at the end of every phase. Hotfixes have no phase boundary, so the check has no automatic trigger. To close the gap, the hotfix flow runs flow.py validate-fix --item FIX-{ee}-{ff}-{nn} right after the GitHub issue is created. The subcommand performs a hotfix-scoped mode-A check:

• FIX row exists in BACKLOG.md with the correct id and refs
• at least one commit on the current branch cites the FIX id in the subject or Refs: trailer
• no FIXME(stub): referencing this FIX-id exists in the codebase without a matching FIX row

The validate-fix call is part of the hotfix lane's mandatory post-fix steps; it is not optional.

Anti-misuse signal. The directions meeting reviews the share of hotfix-lane FIX items per iteration. If hotfixes account for more than 30% of the iteration's work, the lane is being misused as a process bypass and the backlog gets a quality-debt item.

MANDATORY: Backlog as single source of truth (no asking)

Whenever this skill creates or modifies a Feature, Epic, ADR, FIX, IMP, or PLAN, it writes the backlog row in _devprocess/context/BACKLOG.md BEFORE touching the artifact body. Status, phase, last-change, claim, and Refs live in the backlog row, not in the artifact frontmatter.

Defaults when no better value exists. The BACKLOG Status column uses the GitHub-aligned vocabulary (Backlog | Ready | In Progress | In Review | Done). ADR and PLAN files carry their own frontmatter status (Proposed | Accepted | Superseded for ADRs, Draft | Active | Done for PLANs); those values never land in the BACKLOG Status column.

Sync chain on every status or phase change (binding order):

1. Update the backlog row (status, phase, claim, last-change, refs) FIRST
2. Update the artifact body with the substance change
3. Record commit SHA in the backlog row after the commit lands
4. Recompute the dashboard counts at the bottom of the backlog
5. Run /consistency-check mode A at the end of the skill phase

The backlog-first order matters: it prevents the most common drift class observed in the field (status fields stuck at "Planned" while the code shipped). If the backlog write fails, the artifact write does not run.

Full rules and enum values: skills/project-conventions/references/graph-invariants.md, section "Backlog row format".

MANDATORY: Wayfinder maintenance

The wayfinder layer (src/ARCHITECTURE.map plus JSDoc headers in entry-point files plus optional module READMEs) is the only place where current code paths live. /coding owns the runtime upkeep:

• New entry-point file landed -> add a row to src/ARCHITECTURE.map AND write the JSDoc header at the top of the file. Templates: skills/architecture/templates/ARCHITECTURE-MAP-TEMPLATE.md, skills/architecture/templates/JSDOC-HEADER-TEMPLATE.md.
• Entry-point file renamed -> update the matching map row AND the JSDoc header.
• Entry-point file deleted -> remove the map row.
• New module created -> write src/{module}/README.md. Template: skills/architecture/templates/MODULE-README-TEMPLATE.md.

These updates are NOT a separate doc step. They land in the same commit as the code change that triggered them. The verify gate (Phase 4a) checks that src/ARCHITECTURE.map is consistent with the codebase.

Concrete code paths NEVER appear in ADR core sections, FEATURE specs, or PLAN bodies as the source of truth. Those artifacts can carry an optional appendix (## Implementation Notes, ## Code Pointer) that is allowed to go stale; the wayfinder is the canonical source.

This skill has three main responsibilities:

1. Load context from the design phases
2. Critically review it before implementation begins
3. Continuously write back so artifacts always reflect the current state

The actual implementation is done by the Default Claude Code agent. This skill briefs that agent with precise guidelines (see Phase 3 subsections below) so the agent's work is structured, verified, and documented.

MANDATORY: FIX/IMP, depends-on as a graph edge

Chores are not a separate node type. Every piece of work outside of a Feature is either:

• FIX-{ee}-{ff}-{nn} (bug or issue follow-up) at _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md, seeded from templates/FIX-TEMPLATE.md.
• IMPROVEMENT / IMP-{ee}-{ff}-{nn} (technical or other change that is not a feature) at _devprocess/requirements/improvements/IMP-{ee}-{ff}-{nn}-{slug}.md, seeded from templates/IMP-TEMPLATE.md.

Required frontmatter for FIX and IMP:

id: FIX-{ee}-{ff}-{nn}
feature: FEAT-{ee}-{ff}    # mandatory
epic: EPIC-{nn}                    # mandatory
adr-refs: []
plan-refs: []
depends-on: []
created: {YYYY-MM-DD}

FIX and IMP without feature: and epic: are invalid. Status, phase, last-change, and claim live in the backlog row, not in the frontmatter.

Dependencies (depends-on): every artifact (Epic, Feature, ADR, FIX, IMP, PLAN) MAY carry depends-on: [ID, ID, ...] in the frontmatter. The resulting graph is acyclic. Targets must be existing artifact IDs. Details: graph-invariants.md section "Dependencies and implementation order".

MANDATORY: Writing style and humanizer rules

All artifacts produced by this skill follow the rules in skills/project-conventions/SKILL.md under "Writing style for every artifact". Zero em dashes (U+2014, U+2013, double-hyphen substitute). No AI vocabulary words (landscape, nuanced, delve, leverage, crucial, robust, seamless, holistic, foster, ensuring, highlighting, underscoring). No negative parallelisms ("not X but Y"). Active voice by default. Sentence case in headings. No rule-of-three padding. Before saving, scan the artifact for the forbidden vocabulary and fix any hit.

For German artifacts: proper umlauts (ä, ö, ü, ß), not the ae/oe/ue/ss substitutes. Hypothesis and How-Might-We statements are written as full prose paragraphs, not template placeholder lines.

Phase 1: Load Context

Phase 1a: Triage gate (before any edit)

Technical gate that enforces the Phase 0 artifact triage. Phase 0 is the source of truth for the decision tree and exceptions; here we only check that a concrete ID is in scope.

Before the first Edit/Write/Bash call, exactly one of these IDs must be known:

• FEATURE-ID (e.g. FEAT-01-03, spec + optional PLAN)
• IMP-ID (e.g. IMP-007, _devprocess/requirements/improvements/IMP-{ee}-{ff}-{nn}-slug.md)
• FIX-ID (e.g. FIX-012, _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-slug.md)
• ADR-ID (e.g. ADR-04)

If the ID is missing, the skill stops before the first edit and repeats the Phase 0 question (identical wording, not a new variant, so the user is not asked the same thing twice in different words).

After the answer, the ID is anchored in the FEATURE/IMP/FIX frontmatter (feature: and epic: mandatory for IMP and FIX). The backlog row is created or updated FIRST, the frontmatter follows. Exceptions and details: Phase 0 and skills/project-conventions/references/graph-invariants.md (section "Artifact triage at entry point").

Phase 1b: Load Context

Read these documents in order:

REQUIRED:
1. _devprocess/requirements/handoff/plan-context.md (primary input)
2. _devprocess/architecture/ADR-*.md (architecture decisions)
3. _devprocess/requirements/features/FEATURE-*.md (feature details + Success Criteria)
4. CLAUDE.md (project-specific rules)

OPTIONAL (if present):
5. _devprocess/architecture/arc42.md (overall architecture)
6. _devprocess/requirements/epics/EPIC-*.md (strategic context)
7. _devprocess/implementation/plans/PLAN-*.md (prior and active plans; Status=Active carries in-flight work)
8. _devprocess/context/BACKLOG.md (open items, including FIX-{ee}-{ff}-{nn} rows)
9. _devprocess/requirements/fixes/FIX-*.md (open and resolved bug specs)
10. _devprocess/context/HANDOFFS.md (last handoff entry from /architecture)
11. memory/MEMORY.md (architecture key facts)

Dialog check. After loading plan-context.md, scan its ## Dialog section. If there are entries under "Answers from Architect" with Status: Resolved that your previous session did not yet see, read them now. They carry answers to questions you raised in an earlier pass.

If there are "Questions from Coder" entries still at Status: Pending, try to self-answer each one from the current artifacts (updated ADRs, arc42, codebase). For every question you can answer from the artifacts, append the resolution to "Answers from Architect" in the plan-context Dialog section and mark the question Resolved. For every question you still cannot answer, surface the remaining set to the user in a single AskUserQuestion at the end of Phase 1: "N pending Dialog questions could not be self-answered. Address now, defer to end of session, or record as open issues?" Do not block. Proceed with whatever the user chose.

If no plan-context.md exists:

No plan-context.md found. Options:

A) I have FEATURE-*.md files -- work directly with them
B) I want to run the V-Model workflow -> /dia-guide
C) I have an informal description -- work with it

Phase 2: Critical Review

BEFORE an implementation plan is created, critically check the design artifacts against the real codebase. This is the most important step.

2a: Codebase reconciliation

Read the existing codebase and check:

• Do the ADR proposals match the real architecture?
• Are there existing patterns that contradict the proposals?
• Are the tech-stack assumptions in plan-context.md correct?
• Are dependencies or constraints missing?
• Are modules affected by the planned changes but not mentioned in the architecture?

2b: Review output

=== Critical Review: {project/feature} ===

Tech Stack: {from plan-context.md, with corrections if needed}
ADRs: {count} reviewed
Features: {count} reviewed
Success Criteria: {count} to verify

--- Codebase reconciliation ---

CONFIRMED (matches codebase):
- ADR-01: {title} -- proposal fits, {justification}
- FEAT-01-01 SC-01: {criterion} -- realistic

CHANGES NEEDED (divergence from codebase):
- ADR-02: {title} -- proposal: {original}
 Problem: {what doesn't fit}
 Recommendation: {what to do instead}
- FEAT-02-03 SC-02: {criterion}
 Problem: {why not as specified}
 Recommendation: {alternative}

MISSING (not addressed in designs):
- {module/pattern affected but not addressed}

RISKS:
- {risk 1}: {description and mitigation}

--- Decisions ---

Please confirm or correct the change proposals before I create the
implementation plan.

2c: Write changes back

Every change from the review is IMMEDIATELY written back into the source artifacts BEFORE implementation begins:

• ADR changed -> update ADR file:
• Adjust Decision section
• Status -> Accepted (modified by review)
• Document the justification for the change
• ADR rejected -> update ADR file:
• Status -> Deprecated
• Justification and reference to alternative
• Feature SC changed -> update FEATURE file:
• Adjust Success Criteria
• Reason for change as a comment
• plan-context.md corrected -> update file
• New ADR needed -> create new ADR file

After writing back: emit a summary of the changed files.

2d: Signal writeback (drift count)

Append a row to _devprocess/context/METRICS.md under the "Drift count (plan-context.md vs. real code)" table:

• Date: today
• ADR count: how many ADRs were reviewed
• arc42 section count: how many arc42 sections were reviewed
• plan-context item count: how many plan-context entries were checked
• Drift flagged: count of CHANGES NEEDED + MISSING items from the review
• Drift resolved: count of items actually written back in step 2c
• Open: count that remained unresolved (for example because the user wanted to discuss first)

If METRICS.md does not yet exist, copy skills/dia-guide/templates/METRICS-TEMPLATE.md into the file first, then append. A rising drift count over multiple reconciliation runs signals that the ADRs or plan-context are losing touch with reality.

Phase 3: Implementation (delegated to Default Agent)

After the review, implementation is handed off to the Default Claude Code agent. The /coding skill does two things before the agent writes code: (a) persists the plan the agent produces (Phase 3a), and (b) carries cross-cutting protocols the agent binds to for this session (TDD toggle, debugging, verification gate, writeback). These are scoped per sub-section below. Phase 3a itself does not impose a plan shape.

Phase 3a: Plan persistence

Persist the plan as a file (binding).

Every non-trivial implementation run leaves a PLAN-{nn} file behind. Without this file the plan lives only in the agent's session and disappears after context reset.

Location: _devprocess/implementation/plans/PLAN-{nn}-{slug}.md. Template: skills/coding/templates/PLAN-TEMPLATE.md.

What this skill prescribes vs. what the coding agent owns.

This skill prescribes only the traceability wrapper: frontmatter with id / status / date / refs / pair-id, a Change Log section, and an Implementation Notes section. Everything else -- how tasks are decomposed, whether TDD is used, what structure the body has -- belongs to the coding agent that produces the plan. Claude Code has a strong native planning mode, and it keeps improving. This skill persists whatever plan the agent produces; it does not reshape it into a fixed schema that would freeze old patterns into every project.

Flow:

1. Determine the next free 2-digit number by scanning _devprocess/implementation/plans/ (highest NNN + 1). If the directory does not exist, create it and start at 001.
2. Copy the template to _devprocess/implementation/plans/PLAN-{nn}-{slug}.md.
3. Fill the frontmatter: id, title, date (today), feature-refs, adr-refs, bug-refs (if applicable), pair-id, status Draft.
4. Paste the coding agent's plan verbatim into the body section between the frontmatter and the ## Change Log header. If the agent runs in Claude Code, this is the plan Claude Code wrote in plan-mode. Do not edit the structure. If the agent is less capable and produced nothing usable, fall back to the minimal structure described in the template.
5. Flip status to In Progress once implementation begins.
6. Every mid-course trigger (see "Mid-course bug discovery" and "Mid-course design discovery" below) appends a dated entry to the plan's ## Change Log section BEFORE the code edit. Never rewrite earlier entries or earlier task descriptions.

Skip the plan file only for:

• Single-step typo / comment fixes
• Documentation-only edits
• Edits already covered by an existing Active plan (append a Change Log entry instead of creating a new file)

The plan file is part of the artifact report in the Handoff Ritual.

Plan Coverage Gate (binding, runs before Status flips to In Progress).

Regardless of which agent produced the plan, the skill checks four things against the source artifacts. The check happens AFTER the plan body is persisted and BEFORE implementation begins. If any item fails, the flow loops: update the affected artifact, then re-run the gate. No code is written while an item is open.

1. SC coverage. Every Success Criterion from every referenced FEATURE spec either maps to a concrete task in the plan or is explicitly marked "Deferred: {reason}" in the plan body.

• Gap found -> two options: (a) add task(s) to the plan body (agent decides shape), or (b) amend the FEATURE: remove / split / reword the SC, with justification. Every FEATURE amendment bumps the FEATURE's Last updated and gets a one-line comment explaining the change.

2. ADR alignment. Every ADR listed in adr-refs has at least one task that operationalizes its Decision section.

• Gap found -> either add a task, or route through the Mid-course design trigger (the ADR itself may be wrong).

3. Codebase anchoring. Every task names at least one concrete file path (Create / Modify / Test). Abstract tasks like "clean up state management" fail the gate until they name files.
4. Verification gates. The plan body contains at least one build command and one test command that prove the plan done. If the repo has no tests yet, a smoke script is acceptable; the plan names it.

On completion: add a short "## Coverage Gate" block at the bottom of the plan body (before ## Change Log) listing which SC mapped to which task, which SC got deferred, and which ADRs got touched. This block is what a later reviewer (human or agent) reads to verify the gate actually ran.

Re-run the gate whenever a source artifact changes. If a FEATURE, ADR, or plan-context.md is amended while a PLAN is at Status=Active (from codebase reconciliation, mid-course triggers, or external edits), the Coverage Gate runs again on that PLAN before the next code edit. Log the re-run as a Change Log entry with trigger=coverage and the amended artifact ID. This is the writeback loop that keeps the plan honest when upstream artifacts move.

Phase 3a-bis: Guidance for agents without a native planning mode

The rules below are a fallback. If the coding agent is Claude Code (or any agent with its own mature planning conventions), its plan-mode output supersedes this guidance. The skill persists that plan verbatim (per Phase 3a above). Do not rewrite the agent's plan to match the rules below. The point of the rules is to prevent an underpowered agent from producing a plan that is too vague to execute; they are not a ceiling on what a stronger agent can do.

Use the rules when:

• the coding agent has no native planning step, or
• its plan is visibly thin (no file paths, no test strategy, no verification gates) and needs to be repaired before implementation.

Bite-size tasks (2-5 minutes per step):

Every task decomposes into:

1. Write the failing test (one test, one behavior)
2. Run the test -- it MUST fail with the expected reason
3. Write the minimal implementation to make it pass
4. Run the test -- it MUST pass
5. Commit with a conventional prefix (feat/fix/chore/docs/refactor)

Every task has a file list:

• Create: exact/path/to/file.py
• Modify: exact/path/to/existing.py:123-145
• Test: tests/exact/path/to/test.py

No placeholders in the plan:

• Forbidden: "TBD", "TODO", "implement later", "fill in details"
• Forbidden: "Add appropriate error handling", "handle edge cases" (without concrete cases)
• Forbidden: "Write tests for the above" (without actual test code)
• Forbidden: "Similar to Task N" (repeat the code -- tasks may be read out of order)
• Forbidden: Steps that describe WHAT without showing HOW

Self-review after plan creation:

The agent re-reads the plan and checks:

1. Spec Coverage: Does every requirement from plan-context.md map to at least one task?
2. Placeholder Scan: Does the plan contain any red-flag patterns from the list above?
3. Type Consistency: Do function/type/property names match across tasks?

Fix gaps and placeholders inline before implementation starts.

Phase 3b: TDD Mode (optional)

Activation: The user can enable TDD mode explicitly with "enable TDD mode" or by starting /coding with a --tdd hint. Default is: TDD is NOT enforced (because throwaway prototypes and exploration suffer under TDD pressure).

When active, /coding hands this rule to the Default agent for this session:

The rule: No production code without a failing test written first.

The cycle:

1. RED: Write a failing test (one behavior, one assertion)
2. Verify RED: Run the test -- it MUST fail with the expected reason

• If it passes immediately: the test isn't testing the new functionality, fix it
• If it fails with a syntax error: fix the error and re-run

3. GREEN: Write the minimal code to pass the test (no more)
4. Verify GREEN: Run the test -- it MUST pass, no other tests broken
5. REFACTOR: Clean up while keeping tests green (no new behavior)

Exceptions (only with user confirmation):

• Throwaway prototypes
• Generated code
• Configuration files

Phase 3c: Debugging protocol (if a bug appears)

When a test fails unexpectedly during implementation, or behavior is incorrect, or a fix doesn't work, /coding hands the following 4-phase protocol to the Default agent:

The rule: No fixes without root-cause investigation.

Phase A: Root Cause (BEFORE any fix attempt)

1. Read the error message completely -- stack trace, line numbers, codes
2. Check reproducibility -- does it happen every time?
3. Check recent changes -- git diff, last commits, new dependencies
4. In multi-component systems: add logging at every component boundary
5. Trace the data flow backwards -- where does the bad value originate?

Phase B: Pattern Analysis

1. Find working examples in the codebase
2. Read the reference implementation completely (don't skim)
3. List every difference -- even ones that seem irrelevant
4. Check dependencies and config assumptions

Phase C: Hypothesis

1. State one hypothesis: "Root cause is X because Y"
2. Make the smallest possible change to test it
3. One variable at a time
4. If the hypothesis is wrong: form a new one, don't pile fixes

Phase D: Implementation

1. Write a failing test that reproduces the bug
2. Apply exactly one fix that addresses the root cause
3. Verify: test passes, no regressions elsewhere
4. Document the bug as a FIX artefact:
   • Add a row to _devprocess/context/BACKLOG.md under the affected Epic with ID FIX-{ee}-{ff}-{nn}, status, phase, priority (P0/P1/P2), and the commit SHA once the fix lands.
   • Create the detail file at _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md using templates/FIX-TEMPLATE.md. The file carries Symptom, Root cause (causal chain), Fix, Regression test.

Phase D.5: Architecture alarm (after 3+ failed fix attempts)

If three or more fix attempts fail to resolve the situation, this is an architecture problem, not a bug:

• Each fix reveals a new problem in a different place?
• Fixes require "massive refactoring"?
• Each fix creates new symptoms?

Then STOP. No fourth attempt. Instead:

• Question the pattern fundamentally -- is the approach sound?
• Discuss with the user before any more fixes
• This is not a failed hypothesis -- it's a wrong architecture

Writeback: Every bug found, even if the fix is trivial, gets a BACKLOG row (FIX-{ee}-{ff}-{nn}) plus a detail file at _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md carrying symptom, root cause, causal chain, fix description, priority. The BACKLOG row carries status, phase, claim, last-change, and commit SHA; the FIX file carries the substance.

Continuous writeback during implementation

When changes to the planned architecture or features become necessary during implementation, write back IMMEDIATELY:

For every deviation from the plan:

Change during implementation:

WHAT: {what changed}
WHY: {why it was necessary}
AFFECTED ARTIFACTS:
- {ADR-{nn}}: {what to adjust}
- {FEATURE-XXX}: {what to adjust}

Should I write these changes back now? [Y/N]

Triggers for writeback:

• A technical decision deviates from an ADR
• A Success Criterion isn't implementable as specified
• New pattern or new dependency introduced
• Scope change (feature larger/smaller than planned)
• Unexpected constraint discovered

What gets written back:

• PLAN-{nn}: append a Change Log entry (never rewrite past tasks in place)
• ADR: Decision, Status, Implementation Notes
• FEATURE: Success Criteria, Technical NFRs, Definition of Done
• plan-context.md: Tech Stack, Integrations (if fundamentally changed)
• arc42: affected sections (if architecture changes)

Phase 4: Completion -- Final Synchronization

After implementation, final checks and writeback.

Phase 4a: Verification gate before completion

Before /coding declares a task or the whole implementation as done, the following gate function must run. This rule holds regardless of how confident the agent is.

The rule: No completion claims without fresh verification evidence.

If the agent hasn't run the verification command in this message, it cannot claim the task is successful.

The gate function (7 steps, all mandatory):

1. Identify: Which command proves the claim?

• "Tests pass" -> concrete test command with path
• "Build works" -> concrete build command
• "Bug fixed" -> test that reproduces the original symptom

2. Run: Execute the command fully -- not cached, not partial
3. Read: Read the complete output, check exit code, count failures
4. Verify: Does the output confirm the claim?

• No -> report actual status with evidence
• Yes -> formulate the claim with evidence

5. Claim: Only now state the status
6. Reachability check (subtype-aware): for every new top-level symbol introduced this session (class, function, module, command, route, handler, tool registration), verify a caller exists outside the definition file and outside test files. Fall through to the stack-specific tooling defined in references/reachability-by-stack.md (or run the project's dia.config.json -> reachability_check hook script if configured). Subtype-aware:

• subtype: user-facing (default): caller MUST exist outside definition file and outside tests. A symbol that compiles but is never called fails the check.
• subtype: library: caller MUST exist OR the symbol is exported as a public API entry point and documented as such. On fail, the FEATURE Done-status is locked. Options: wire it up, demote subtype: to library with public API documentation, or open a FIX-{ee}-{ff}-{nn} row "Wiring offen" and keep the FEATURE at Active in the backlog.

7. Activation-path check: for every FEATURE moving to Done in this session, read the ## Activation Path section in the FEATURE spec and verify each entry exists in the code:

• command -> command name registered in command registry
• route -> route path registered in router
• UI-element -> element rendered in component tree or template
• endpoint -> handler registered with the framework
• scheduled-job -> schedule registered with the scheduler
• tool -> tool name registered in the agent tool registry
• hotkey -> hotkey registered with the platform
• public-API -> symbol exported in the package's public surface The check is a grep or AST query. The activation path string in the FEATURE spec MUST match an actual identifier in the code. On fail, the FEATURE Done-status is locked.

Forbidden language without fresh verification:

• "should work", "probably okay", "looks good"
• "tests should be green now"
• "the change should fix the bug"
• Any statement implying success without running the command

Common failures -- what is not enough:

Phase 4b: Regression test cycle (for bug fixes)

Every bug fix goes through this 6-step cycle to prove the regression test actually catches the regression:

1. Write the regression test reproducing the bug behavior
2. Run 1: Run the test -- it MUST pass (because the fix is already in)
3. Temporarily revert the fix (git stash or code revert)
4. Run 2: Run the test -- it MUST FAIL

• If it passes: the test isn't catching the bug, fix the test

5. Restore the fix (git stash pop or code restore)
6. Run 3: Run the test -- it MUST pass again

Only when all three runs return the expected result is the bug marked as resolved and the regression test marked as valid.

Documentation: The FIX detail file at _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md gets a note in its ## Regression test section: "Regression test verified via red-green cycle on {date}".

Phase 4c: Deferred-stub marker convention (binding)

A stub implementation is any code that intentionally returns a no-op, empty result, or hard-coded placeholder while waiting on later wiring, external data, an upstream feature, or a real implementation in a later phase. Stubs are normal in iterative development; what is forbidden is silent stubs.

Every stub MUST carry a FIXME(stub): marker AND a paired FIX-{ee}-{ff}-{nn} row in the backlog. The two are bidirectionally bound: each marker references its FIX-ID, each FIX-row that documents a stub references at least one source location.

Marker syntax (per-language comment style, identical content):

// FIXME(stub): <one-line reason> -- see FIX-{ee}-{ff}-{nn}
# FIXME(stub): <one-line reason> -- see FIX-{ee}-{ff}-{nn}

Use // for C-family languages (TypeScript, JavaScript, Java, Go, Rust, C#, Swift, Kotlin). Use # for Python, Ruby, R, shell scripts.

The FIX-row in _devprocess/context/BACKLOG.md and its detail file at _devprocess/requirements/fixes/FIX-{ee}-{ff}-{nn}-{slug}.md carry the context: why the stub is there, what unblocks it, what to do when it is unblocked.

/consistency-check Mode A enforces the binding (E-13):

• Every FIXME(stub): in the source tree must reference an open FIX-row by ID; missing or unresolved IDs surface as stub-without-fix-row findings.
• Every FIX-row whose notes contain Wiring offen, stub, or similar deferral language must reference at least one source location; missing references surface as fix-without-stub-evidence findings.

Why bidirectional. A marker without a FIX-row is invisible at the backlog level; nobody plans to remove it. A FIX-row without a marker is stale paperwork; nobody can find the actual code to remove. The bidirectional binding turns silent deferrals into auditable items.

Mid-course bug discovery (binding trigger)

If a NEW bug surfaces while implementing the current plan (not in the original feature specs, ADRs, or FIX-list), the coding flow MUST pause and route through the artefact layer BEFORE writing the fix. Skipping this step leaks code changes without backlog trace.

Mid-course handling, do NOT fix the bug silently:

1. STOP the current code edit. Do not write the fix yet.
2. Triage:
 - Is this a BUG in shipped code? -> create BUG-NNN
 - Is this a missing requirement in plan? -> create FEAT-NN-NN
 - Is this a design gap? -> amend ADR / arc42
3. Write a minimal root-cause analysis in _devprocess/analysis/
 (3-10 lines is fine: problem, cause, fix direction, risk)
4. Add the new item to _devprocess/context/BACKLOG.md under
 the active Epic so it appears in the backlog before any code
 touches disk
5. Append a Change Log entry to the active PLAN-{nn} file with
 trigger=bug, the new BUG-NNN reference, and a one-line summary
 of what the fix changes. Never rewrite past tasks in place.
6. NOW write the fix. Commit message cites BOTH the in-progress
 FEAT-NN-NN and the new BUG-NNN (e.g.
 `Refs: FEAT-05-07, BUG-018, PLAN-12`)
7. After the fix: run the standard Final synchronization block
 below, marking the new BUG-NNN as resolved

Why this matters: bugs surfaced during beta testing of a real downstream project got fixed in code first and documented only after release, so the backlog drifted from the code state for days. This trigger closes that gap.

Mid-course design discovery (binding trigger)

If the implementation reveals that an architectural decision does not match reality (ADR says X, the codebase proves Y works better, or

…(truncated)