tdd-pipeline

name	tdd-pipeline
version	0.21.0
description	A rigorous TDD development workflow enforcing Red-Green-Refactor at the pipeline level: Product Design → Technical Solution → Test Plan → Test Code → Business Code → Pre-Release Testing → System Quality Audit → Acceptance Testing. Phases 1–5 are creation phases with mandatory Ralph-loop review. Phase 6 is the pipeline's validation closure — systematic pre-release testing with bug root cause analysis and rollback paths. Phase 7 is an incremental system-level audit (16-pattern catalog, pair discovery, execution-order analysis). Phase 8 is functional acceptance — requirements traceability, AC-level verification, independent check, and release decision. No business code is written until tests exist and fail.
triggers	["tdd","tdd pipeline","test-driven","red green refactor","write tests first","pre-release","release test","ship it","go/no-go","ready to deploy","产品设计","技术方案","测试驱动","测试方案","先写测试","上线前测试","发版前检查","回归测试"]
argument-hint	<feature description or user request>
level	3

TDD Pipeline Skill

Overview

The TDD Pipeline enforces a strict, phase-gated workflow where tests are the primary specification artifact. Business code is the implementation detail that makes tests pass — nothing more.

Core Principle: If you cannot write a failing test for it, you do not understand it well enough to build it.

Pace Principle: 慢就是快，欲速不达 (Slow is fast; haste makes waste). The Ralph loop's review rounds are not overhead — they are where quality is built. Every shortcut through a gate saves minutes now but costs hours in debugging later.

The 8 Phases

Phases 1–5 are creation phases — they produce artifacts reviewed by Ralph loop. Phase 6 is the validation closure — it validates the entire pipeline's output through systematic testing, with its own quality mechanisms (not Ralph loop). Phase 7 is an incremental system audit — it runs after Phase 6 completes, applying a broader 16-pattern catalog, integration pair discovery, and execution-order analysis to find issues Phase 6 missed. Phase 8 is functional acceptance — it traces requirements to implementation, verifies every AC has evidence, and presents the release decision to the user.

Ralph Loop Review (Phases 1–5)

Phases 1–5 each end with a mandatory Ralph-loop review before proceeding. Phase 6 uses a different quality mechanism — see phase-6-pre-release-testing.md for details. See ralph-review-loop.md for the full protocol.

After completing each phase deliverable (Phases 1–5), run the ralph-review-loop.md protocol before user approval.

GPAV (Guarded Pipeline Authority Verification)

When the Watchdog is active, each review round's findings MUST be submitted via ralph_round_finding for authoritative tally tracking. See ralph-gpav.md for the full protocol (format, validation, RPS scanner).

Progressive Disclosure

At each phase, read ONLY the corresponding phase-N-*.md file for detailed instructions. Do NOT load all phase files at once. The ralph-review-loop.md protocol is loaded automatically at each phase's review step.

• Phase 1 → phase-1-product-design.md (Requirements Document)
• Phase 2 → phase-2-technical-solution.md (Technical Design Document)
• Phase 3 → phase-3-test-plan.md (Test Plan Document)
  • Loaded with Phase 3 review → phase-3-edge-reference.md (edge case depth verification — reviewer only, do NOT load during deliverable creation)
• Phase 4 → phase-4-test-code.md (Test Files)
  • After test code, before Ralph review → phase-4-test-infrastructure-checklist.md (structural test infrastructure audit: 9-item checklist + verification gate)
• Phase 5 → phase-5-business-code.md (Business Code)
• Phase 6 → phase-6-pre-release-testing.md
  • On sub-phase failure → additionally load phase-6-root-cause-investigation.md
• Phase 7 → phase-7-system-quality-audit.md (loaded after Phase 6 completes; 16-pattern catalog with grep commands, integration pair discovery, execution order analysis)
• Phase 8 → phase-8-acceptance-testing.md (loaded after Phase 7 completes; functional acceptance: requirements traceability, AC-level verification, independent check, release decision)
• Review files (loaded at each phase's review step, see ralph-review-loop.md §Review Checklists):
  • Design review (Phase 1–3) → review-design.md
  • Code review (Phase 4–5) → review-code.md
  • Fact-Gather subagent (location mapping) → review-fact-gather.md
  • Precision filter (dual-pass mode) → review-precision-filter.md
  • Eval-Fix subagent (evaluate + fix suggestions) → review-evalfix.md
• Ralph loop support files (loaded on demand):
  • GPAV protocol (Watchdog active) → ralph-gpav.md
  • Continuation protocol (Rounds 2+) → ralph-continuation.md
  • Contested issue protocol → ralph-contested.md (loaded when C/H/M is REJECTed)
  • Worked examples (contested issues, stop scenarios) → ralph-examples.md
  • Review log template → ralph-log-template.md
  • Severity migration guide (pre-v0.13 → v0.13) → severity-migration.md
• Task tree → task-tree.md (loaded ONLY when Split Decision evaluates to SPLIT=true)

Skill Reload Protocol

During Ralph loop execution, the main agent must maintain a rounds_since_reload counter in every [ROUND N CLOSE] block (defined in ralph-review-loop.md §SELF-MONITORING):

• Increment by 1 each round
• When it reaches 5, or when a capability-degradation signal fires: execute Read("skill/ralph-review-loop.md") before the next round's Step 0, then reset to 0
• Reload does NOT reset round count or CHM tally

This rule is the orchestrator-layer backstop for ralph-review-loop.md §SELF-MONITORING. Both are active simultaneously.

Severity Systems

The pipeline uses two severity systems for different scopes:

System	Used In	Levels	Gate Threshold	Purpose
Ralph loop severity	Phases 1–5 review rounds	C/H/M/P/L/I	Zero C/H/M to pass gate	Review artifact quality — defined in ralph-review-loop.md
Pipeline severity	Phase 6–7 gates	C/H/M/P/L	Zero C/H to pass gate (M recorded but does not block)	Release readiness — defined in phase-7-system-quality-audit.md
Phase 8 diagnosis gate	Phase 8 acceptance	Diagnosis-based BLOCKERs + Phase 7 unresolved C/H + Phase 6 system-level FAILs	Zero BLOCKERs to pass gate (see phase-8-acceptance-testing.md Diagnosis Table)	Requirements completeness — BLOCKERs are per-diagnosis, not C/H severity

• Key difference: Ralph loop gate blocks on M (defect-tier); Pipeline gate (Phase 6–7) blocks on C/H only (M is advisory). Phase 8 uses its own diagnosis-based gate — a No Test Code or Weak core diagnosis is a BLOCKER regardless of severity classification.
• Ralph loop severity: C/H/M (defect tier, counted in stop condition) + P (proposal, not counted) + L (low, not counted) + I (info). See ralph-review-loop.md for full definitions.
• Pipeline severity: C (critical) + H (high) + M (medium) + P (petty) + L (low). Note: Pipeline P = petty (minor formatting concern), not to be confused with Ralph P = proposal (architectural restructuring suggestion).
• Phase 8 secondary AC threshold: If >20% of secondary ACs have Weak diagnosis (L3-only evidence, no L1/L2), the excess above 20% are flagged as warnings in the acceptance report (the first N = floor(20% × total) are accepted as ✱, ordered by AC# numeric suffix lowest first). (L1=unit test, L2=integration/E2E, L3=manual, L4=Part 4 independent verification metadata — L1/L2/L3 are per-AC evidence levels; L4 is report-level metadata, not AC evidence. Full definitions in phase-8-acceptance-testing.md Evidence Levels table.) See phase-8-acceptance-testing.md Secondary Threshold Check.

Anti-Patterns

Anti-Pattern	Why It's Wrong	Fix
Business code before tests	Violates TDD, creates untested code	STOP → write test first
Test passes immediately	Business code leaked or test is wrong	Remove leaked code or fix test
Change tests to fit impl	Tests are the spec, not the code	Fix the code, not the test
Skip refactor step	Accumulates technical debt	Always refactor when green
Bypass Ralph gates (Phase 1–5)	Hidden flaws propagate downstream	Run until gate pass, enforce zero C/H/M
One giant test file	Poor organization, hard to maintain	1 file per component/module
Only happy-path tests	Misses real-world failures	MUST test errors + boundaries
Phase 6 partial re-run	Fixes may introduce regressions	Always full re-run from Phase 6 Sub-Phase 0, then continue through Phase 7→8
Skip 追问 (root cause investigation) when Phase 6 fails	Fixes symptom, not root cause	Run Layer Isolation + 5-Why + T1-T3
Skip Phase 7 system audit	Undocumented system defects may reach production	Always run Phase 7 after Phase 6 passes
Accept BLOCKERs without resolution	Release quality unknown — BLOCKERs were reported but ignored	Report BLOCKERs to user for decision; do not proceed to release while BLOCKERs remain unresolved (exception: escalated Unknown BLOCKERs where Phase 6 re-run already failed — user may accept risk per Phase 8 Part 5 Step 1)

Split Decision

Before writing any phase deliverable, evaluate structural complexity:

write_outline()                    // list planned sections, modules, stories, components

# "modules" and "stories" are phase-adaptive:
#   Phase 1: stories = user stories
#   Phase 2: stories = components
#   Phase 3: stories = test groups
#   Phase 4: stories = test modules
#   Phase 5: stories = implementation files
if count(modules) >= 3 OR count(stories) >= 5:
    SPLIT = true
    if count(modules) < 3:
        # Stories triggered the split; group stories into 3-7 cohesive modules
        modules = group_by_cohesion(stories, target=clamp(count(stories)/2, 3, 7))
    elif count(modules) > 7:
        # Too many modules; merge small ones into larger cohesive groups
        modules = merge_smallest(modules, target=7)
    # Result: 3-7 modules, each a cohesive group for parallel execution
else:
    SPLIT = false                                    // write as single document

If SPLIT = true, load task-tree.md for the decomposition, execution, context-reading, and versioning protocols. If SPLIT = false, proceed normally with a single deliverable document.

Rollback from Phase 6

When Phase 6 discovers issues, the 追问 (root cause investigation) determines which phase to roll back to:

Root Cause Layer	Rollback To	Re-run Scope
Test gap	Phase 4	Phase 4 → 5 → 6 → 7 → 8
Code bug	Phase 5	Phase 5 → 6 → 7 → 8
Design flaw	Phase 2	Phase 2 → 3 → 4 → 5 → 6 → 7 → 8
Requirement misunderstanding	Phase 1	Full pipeline
Config/environment only	Fix config	Phase 6 only (full re-run), then 7 → 8

See phase-6-pre-release-testing.md for the complete 追问 (root cause investigation) protocol with termination criteria and rollback procedures. (This table is mirrored in phase-6-pre-release-testing.md — keep in sync.)

Task Naming Convention

All review artifacts use a standardized naming convention:

• Requirement ID: yymmdd-summary (e.g. 260608-user-auth), confirmed with user during Phase 1 requirements clarification
• TDD phase: p1–p8 (numeric identifier, not phase name)
• Review stage: recall, factgather, precision, evalfix

Artifact	Pattern
Deliverable	{yymmdd-summary}/p{N}-{desc}.md
Review temp	r{round}-{stage}-{sub_task_id}.json
Review log	{yymmdd-summary}/review-log-p{N}-r{round}.md
Split plan	{yymmdd-summary}/split-plan-p{N}-r{round}.md

See ralph-review-loop.md §Task Naming Convention for the complete specification.