C31 Coding Discipline

"NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST." — Iron Law of TDD

Enforced development workflow for coding tasks. Not a suggestion — a gate. Each step completes before the next begins. Skill routing conflicts (C31 vs wayfinding vs gsd) resolve in docs/SKILL-ROUTER.md.

7-Step Workflow

1. Brainstorm     ← If requirements unclear, run C31-brainstorm first
2. Worktree       ← git worktree add .feature-branch. Isolated development
3. Plan           ← C31-plan with No Placeholders enforced
4. TDD            ← RED → GREEN → REFACTOR for every unit
5. Execute        ← C31-work wave execution, fresh subagent per task
6. Inline Review  ← 30-second checklist (not 25-minute subagent loops)
7. Finish         ← Verify tests → merge / PR / keep / discard

Step 1: Brainstorm (Conditional)

If the coding task is unclear, ambiguous, or cross-cutting, run C31-brainstorm to produce a requirements doc. If already clear, skip to Step 2.

Gate: Requirements doc must exist (from brainstorm or user) before planning.

Step 2: Worktree (Mandatory for Non-Trivial Tasks)

git worktree add .worktrees/feature-name -b feature/feature-name
cd .worktrees/feature-name

• Verify clean test baseline: npm test / pytest / etc. must pass before changes.
• If tests fail on baseline → fix baseline first, or document known failures.

Trivial fast-path: single-file typo fix, one-line change → skip worktree, edit in place.

Step 3: Plan (Mandatory)

Run C31-plan with No Placeholders enforced:

Every unit must contain:
- Exact file path (repo-relative)
- Complete code blocks (not "similar to Task N")
- Exact commands with expected output
- Test scenario: input → action → expected outcome

Placeholder Detection Gate:

Plan granularity: 2–5 minutes per unit. If a unit takes >5 minutes, split it.

Step 4: TDD — RED → GREEN → REFACTOR (Mandatory)

For every implementation unit:

RED: Write one minimal failing test

• Seam first (mattpocock/tdd): test only at pre-agreed public seams — before writing any test, name the seams under test and confirm with the user. No test at an unconfirmed seam.
• One behavior per test
• Clear descriptive name
• Real code in test (no mocks unless external API)
• Run test. Confirm it fails for the expected reason. Never skip verification.
• No tautological tests (mattpocock/tdd): the assertion must never recompute the expected value the way the code does — expected values come from an independent source of truth (known-good literal, worked example, spec). A test that passes by construction can never disagree with the code.

GREEN: Write simplest code to pass

• Minimal implementation. No gold plating.
• Run test. Confirm pass + all other tests still pass + no warnings.

REFACTOR: Clean up, keep tests green

• Remove duplication. Improve naming. Simplify.
• Run full suite after each refactor.

Step 5: Execute (Wave Parallel)

Run C31-work with wave analysis:

• Wave 1: independent tasks → parallel subagents
• Wave 2+: dependent tasks → sequential
• Fresh subagent per task (context isolation — no pollution from prior tasks)

Commit per task (atomic, bisectable, revertible; conventional-commit message; no commit without passing tests):

git add <task-specific-files>
git commit -m "feat(scope): U3 Add parser coverage"

Step 6: Inline Review (30-Second Checklist)

After each task (or wave), run this checklist — do NOT spawn a subagent:

If any check fails: fix immediately before proceeding.

Only spawn subagent reviews for: security review, adversarial review, or complex architecture review (Superpowers v5.0.6: 30s checklist ≈ 25min subagent loop, same quality).

Step 7: Finish — Merge / PR / Keep / Discard

cd main-repo
npm test  # full suite must pass

git merge feature/feature-name              # merge to main
git push origin feature/feature-name        # open PR
git worktree remove .worktrees/feature-name # cleanup

If tests fail: return to Step 4. Do not merge with failing tests.

Type System Discipline (pstack, merged 2026-08-19)

The type checker is a proof assistant — make illegal states unrepresentable at compile time instead of catching them with runtime probes. Our incident history (W21b kind never set, analog selective-copy) is the optional-field-bag disease; this table is the vaccine. Full principle: wayfinding/ pstack principle-type-system-discipline; patterns: its references/patterns.md.

Guardrails

• 3-Fix Rule (from C31-debug): after 3 failed fix attempts on a bug, STOP — this is an architectural problem. Escalate to human.

Output Format

After completing the 7 steps:

✅ C31-coding-discipline complete

Branch: feature/feature-name
Commits: N
Tests: all pass (X total, 0 failures)
Inline reviews passed: N
Files changed:
  - path/to/file1 (lines +X -Y)
  - path/to/file2 (lines +X -Y)

Residuals (if any):
  - [description] → /tmp/c31-coding-residuals.md

Anti-Rationalization Guard