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.

1. 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.

1. Verify the branch matches feature/- (or

fix/... / chore/...). On a wrong branch, AskUserQuestion to switch.

1. Skill-triggered GitHub integration:

`` python3 tools/github-integration/flow.py create-issue --item python3 tools/github-integration/flow.py open-draft-pr --item ``

1. At Handoff Ritual end, tag the phase:

`` python3 tools/github-integration/flow.py tag-phase --item --phase code ``

1. 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).

1. FIX for a bug or drift on an existing feature.
2. 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).

1. 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.

1. Run the phase-end commit (per team-workflow.md) with message

chore(fix): FIX-{ee}-{ff}-{nn} bug captured. The commit creates the fix/- branch via the commit-boundary check.

1. 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)

Trivial bugs may fix first, document after, when all five hold: at most 3 files; no new feature or dependency; no breaking change to a public API; under 15 minutes; existing FEAT as parent. Any miss -> standard bug-capture flow.

Flow when allowed:

1. Fix immediately; run relevant tests.
2. Write the FIX BACKLOG row and detail file. Commit

fix: FIX-{ee}-{ff}-{nn} with Refs: trailer.

1. In github-sync mode: gh issue create --title "FIX-{ee}-{ff}-{nn}: {slug}" --label "fix,hotfix",

then python3 tools/github-integration/flow.py sync-status --item FIX-{ee}-{ff}-{nn}.

1. Always close with python3 tools/github-integration/flow.py validate-fix --item FIX-{ee}-{ff}-{nn}.
2. Acknowledge in chat: modified files, FIX-ID, issue URL, validate-fix verdict.

The regression-test cycle (Phase 4b) still runs; the 15-minute budget includes the test.

Four safety nets keep the lane honest:

• FIX-Row in BACKLOG.md (mandatory, even retroactively).
• Commit cites FIX-ID in subject and Refs: trailer.
• Deferred-stub markers bind // FIXME(stub): ... -- see FIX-{id} to

the FIX row's Notes column.

• Regression-test cycle writes a ## Regression test entry.

validate-fix runs the hotfix-scoped consistency check: FIX row exists with correct id and refs; at least one commit cites the id; no orphan FIXME(stub): references.

Anti-misuse: if hotfixes exceed 30% of an iteration, the lane is being abused as a process bypass; file 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 vocabulary, defaults per artifact type, and frontmatter status fields for ADR/PLAN: see skills/project-conventions/SKILL.md#canonical-specs (Backlog vocabulary, Frontmatter spec).

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
3. Record commit SHA after the commit lands
4. Recompute dashboard counts
5. Run /consistency-check mode A at the end of the skill phase

Backlog-first order prevents the dominant drift class (status stuck at "Ready" while code shipped). If the backlog write fails, the artifact write does not run. Full rules: 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 a FIX-{ee}-{ff}-{nn} at _devprocess/requirements/fixes/ (seeded from templates/FIX-TEMPLATE.md) or an IMP-{ee}-{ff}-{nn} at _devprocess/requirements/improvements/ (seeded from templates/IMP-TEMPLATE.md).

Frontmatter spec (required keys, forbidden keys, feature: / epic: mandatory for FIX and IMP, depends-on semantics): see skills/project-conventions/SKILL.md#canonical-specs (Frontmatter spec). Details on dependency graph acyclicity: graph-invariants.md (section "Dependencies and implementation order").

MANDATORY: Writing style

See skills/project-conventions/SKILL.md#canonical-specs (Writing style). Same rules apply to every artifact this skill produces.

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} | Success Criteria: {count}

| Category        | Item                       | Action                        |
|-----------------|----------------------------|-------------------------------|
| CHANGES NEEDED  | ADR-02: {title}            | {recommendation}              |
| MISSING         | {module/pattern}           | {what to add}                 |
| RISKS           | {risk}                     | {mitigation}                  |

Please confirm or correct before I create the implementation plan.

CONFIRMED items are omitted; absence from the table means "matches the codebase". Only divergence, gaps, and risks are listed.

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 with three columns:

| Date | Drift flagged | Drift resolved | |------|---------------|----------------|

Drift flagged = count of CHANGES NEEDED + MISSING items. Drift resolved = items actually written back in step 2c. If METRICS.md does not yet exist, copy skills/dia-guide/templates/METRICS-TEMPLATE.md first, then append. Rising drift means 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 /

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pssah4
• Source: pssah4/digital-innovation-agents
• License: MIT
• Homepage: https://pssah4.github.io/digital-innovation-agents/

Install and usage instructions live in the source repository linked above.