Spec Workflow

Surveyverse Spec Workflow

Announce at start: "Running spec-workflow Stage N — [stage name]."

Five stages, always in order. Stages 2 and 2 Resolve are conditional — skip them if the spec contains no variance estimation, estimators, or statistical inference:

1. Stage 1 — Draft: Write the spec
2. Stage 2 — Methodology review: Single exhaustive statistical pass (conditional)
3. Stage 2 Resolve — Lock methodology: Resolve all methodology issues; spec is methodology-locked after this
4. Stage 3 — Code review: Adversarial architecture/API pass (may run multiple times)
5. Stage 4 — Resolve: Interactively work through code review issues; log decisions

After the spec is approved, move to /implementation-workflow.

digraph spec_stages {
    rankdir=LR;
    S1 [label="Stage 1\nDraft", shape=box];
    S2 [label="Stage 2\nMethodology Review", shape=box];
    S2R [label="Stage 2 Resolve\nLock Methodology", shape=box];
    S3 [label="Stage 3\nCode Review", shape=box];
    S4 [label="Stage 4\nResolve + Log", shape=box];
    done [label="→ /implementation-workflow", shape=doublecircle];

    S1 -> S2;
    S2 -> S2R [label="issues found"];
    S2 -> S3 [label="N/A"];
    S2R -> S3;
    S3 -> S4 [label="issues found"];
    S3 -> done [label="clean"];
    S4 -> done;
}

Stage Routing

Determine which stage the user wants from context. If unclear, use AskUserQuestion:

question: "Which stage of the spec workflow do you want to run?"
header: "Stage"
multiSelect: false
options:
  - label: "Stage 1 — Draft the spec"
    description: "Write a new spec from scratch."
  - label: "Stage 2 — Methodology review"
    description: "Statistical correctness pass (conditional: only for specs with variance estimation or inference). Single exhaustive pass — finds all issues before concluding."
  - label: "Stage 2 Resolve — Resolve methodology issues"
    description: "Work through the methodology review file. Methodology-locks the spec after completion."
  - label: "Stage 3 — Code/architecture review"
    description: "Adversarial API, contract, and test-plan pass. Can run multiple times."
  - label: "Stage 4 — Resolve code issues + log decisions"
    description: "Interactively work through the code review file issue by issue."

Then read the corresponding reference file before doing anything else:

Common Shortcuts to Resist

Rules in Context

Every stage works alongside — never instead of — these rule files:

When a spec decision touches one of these rules, cite the rule file. When the spec is silent on something these rules already define, note that the rule is authoritative — the spec doesn't need to repeat it.

File Locations

The {id} matches the feature branch identifier (e.g., phase-2, survey-srs).

Spec:                    plans/spec-{id}.md
Methodology review:      plans/spec-methods-review-{id}.md
Code review:             plans/spec-review-{id}.md
Decisions log:           plans/decisions-{id}.md

Determining {id}: Infer from user context first (e.g., "phase 2 spec" → phase-2, "survey-srs spec" → survey-srs). If the spec file already exists, derive {id} from its filename. If ambiguous, ask the user before reading or writing any file.