Surveyverse Implementation Workflow
Announce at start: "Running implementation-workflow Stage N — [stage name]."
This skill governs implementation plan work for surveycore (and other surveyverse
packages). Three stages, always in order:
- Stage 1 — Draft: Write the implementation plan from the finalized spec
- Stage 2 — Review: Adversarial batch pass; saves all issues to a file
- Stage 3 — Resolve: Interactively work through issues and log decisions
After the plan is approved, hand off to:
/r-implement — section-by-section with manual oversight between sections/auto-ship — fully autonomous: implements, commits, PRs, monitors CI, and
merges each section without manual handoffs
digraph impl_stages {
rankdir=LR;
S1 [label="Stage 1\nDraft Plan", shape=box];
S2 [label="Stage 2\nAdversarial Review", shape=box];
S3 [label="Stage 3\nResolve + Log", shape=box];
done [label="→ /r-implement\nor /auto-ship", shape=doublecircle];
S1 -> S2;
S2 -> S3 [label="issues found"];
S2 -> done [label="clean"];
S3 -> S2 [label="new issues\ndiscovered"];
S3 -> done [label="all resolved"];
}
Stage Routing
Determine which stage the user wants from context. If unclear, use the
AskUserQuestion tool:
question: "Which stage of the implementation workflow do you want to run?"
header: "Stage"
multiSelect: false
options:
- label: "Stage 1 — Draft the plan"
description: "Write the implementation plan from the finalized spec."
- label: "Stage 2 — Adversarial review"
description: "Full batch pass over the plan; saves all issues to a file."
- label: "Stage 3 — Resolve issues"
description: "Interactively work through the review file issue by issue."
Then read the corresponding reference file before doing anything else:
| Stage |
Reference file |
| 1 |
.claude/skills/implementation-workflow/references/stage-1-draft.md |
| 2 |
.claude/skills/implementation-workflow/references/stage-2-review.md |
| 3 |
.claude/skills/implementation-workflow/references/stage-3-resolve.md |
Task Granularity (Stage 1)
Each task in the plan should be one action (2–5 minutes). TDD sub-steps must be
explicit steps, not collapsed into one: write the failing test → run to confirm
failure → write minimal code → run to confirm passing → commit. This granularity
lets r-implement work through tasks without ambiguity about what "done" means for
each step.
Common Shortcuts to Resist
| Rationalization |
Why it fails |
| "The plan is clear enough, Stage 2 would just nitpick" |
Stage 2 catches missing error paths, wrong task order, and DRY violations before code is written. |
| "Some issues are minor, I'll resolve them later" |
plans/decisions-{id}.md must be fully populated before handing off. |
| "We can figure out edge cases during implementation" |
Edge cases discovered during implementation are plan bugs. Resolve them here. |
Rules in Context
Every stage works alongside — never instead of — these rule files:
| Rule file |
What it governs |
code-style.md |
Indentation, pipe, air formatter, S7 patterns, cli error structure, argument order, helper placement |
r-package-conventions.md |
:: usage, NAMESPACE, roxygen2, @return, @examples, export policy |
surveycore-conventions.md |
Naming patterns (get_*, extract_*, set_*), @family, return visibility, haven handling |
testing-standards.md |
test_that() scope, 98% coverage, assertion patterns, data generators |
testing-surveycore.md |
test_invariants(), layer 1 vs layer 3 error testing, make_survey_data(), numerical tolerances |
github-strategy.md |
Branch naming, PR granularity, commit format, merge strategy |
File Locations
The {id} matches the feature branch identifier (e.g., phase-2, survey-srs).
Implementation plan: plans/impl-{id}.md
Plan review: plans/plan-review-{id}.md
Decisions log: plans/decisions-{id}.md
1---2name: implementation-workflow-23description: Use this skill for implementation plan work — drafting a plan from a finalized spec, running an adversarial review of the plan, or resolving plan issues interactively. Trigger when the user says "build the implementation plan", "draft the plan", "review the plan", "resolve plan issues", or "implementation plan". Always runs after spec-workflow is complete. Has three stages: Stage 1 (draft plan), Stage 2 (adversarial review), Stage 3 (resolve + decisions log). After the plan is approved, hand off to /r-implement (section-by-section with manual oversight) or /auto-ship (fully autonomous end-to-end execution).4---5
6# Surveyverse Implementation Workflow
7
8**Announce at start:** "Running implementation-workflow Stage N — [stage name]."
9
10This skill governs implementation plan work for surveycore (and other surveyverse
11packages). Three stages, always in order:
12
131. **Stage 1 — Draft:** Write the implementation plan from the finalized spec
142. **Stage 2 — Review:** Adversarial batch pass; saves all issues to a file
153. **Stage 3 — Resolve:** Interactively work through issues and log decisions
16
17After the plan is approved, hand off to:
18- `/r-implement` — section-by-section with manual oversight between sections
19- `/auto-ship` — fully autonomous: implements, commits, PRs, monitors CI, and
20 merges each section without manual handoffs
21
22```dot
23digraph impl_stages {
24 rankdir=LR;
25 S1 [label="Stage 1\nDraft Plan", shape=box];
26 S2 [label="Stage 2\nAdversarial Review", shape=box];
27 S3 [label="Stage 3\nResolve + Log", shape=box];
28 done [label="→ /r-implement\nor /auto-ship", shape=doublecircle];
29
30 S1 -> S2;
31 S2 -> S3 [label="issues found"];
32 S2 -> done [label="clean"];
33 S3 -> S2 [label="new issues\ndiscovered"];
34 S3 -> done [label="all resolved"];
35}
36```
37
38<HARD-GATE>
39Do not hand off to `/r-implement` or `/auto-ship` until Stage 3 is complete,
40all issues in `plans/plan-review-{id}.md` are resolved, and
41`plans/decisions-{id}.md` is populated. No implementation begins until the
42plan is fully approved.
43</HARD-GATE>
44
45---
46
47## Stage Routing
48
49Determine which stage the user wants from context. If unclear, use the
50`AskUserQuestion` tool:
51
52```
53question: "Which stage of the implementation workflow do you want to run?"
54header: "Stage"
55multiSelect: false
56options:
57 - label: "Stage 1 — Draft the plan"
58 description: "Write the implementation plan from the finalized spec."
59 - label: "Stage 2 — Adversarial review"
60 description: "Full batch pass over the plan; saves all issues to a file."
61 - label: "Stage 3 — Resolve issues"
62 description: "Interactively work through the review file issue by issue."
63```
64
65Then read the corresponding reference file before doing anything else:
66
67| Stage | Reference file |
68|---|---|
69| 1 | `.claude/skills/implementation-workflow/references/stage-1-draft.md` |
70| 2 | `.claude/skills/implementation-workflow/references/stage-2-review.md` |
71| 3 | `.claude/skills/implementation-workflow/references/stage-3-resolve.md` |
72
73## Task Granularity (Stage 1)
74
75Each task in the plan should be one action (2–5 minutes). TDD sub-steps must be
76explicit steps, not collapsed into one: write the failing test → run to confirm
77failure → write minimal code → run to confirm passing → commit. This granularity
78lets r-implement work through tasks without ambiguity about what "done" means for
79each step.
80
81## Common Shortcuts to Resist
82
83| Rationalization | Why it fails |
84|---|---|
85| "The plan is clear enough, Stage 2 would just nitpick" | Stage 2 catches missing error paths, wrong task order, and DRY violations before code is written. |
86| "Some issues are minor, I'll resolve them later" | `plans/decisions-{id}.md` must be fully populated before handing off. |
87| "We can figure out edge cases during implementation" | Edge cases discovered during implementation are plan bugs. Resolve them here. |
88
89---
90
91## Rules in Context
92
93Every stage works alongside — never instead of — these rule files:
94
95| Rule file | What it governs |
96|---|---|
97| `code-style.md` | Indentation, pipe, air formatter, S7 patterns, cli error structure, argument order, helper placement |
98| `r-package-conventions.md` | `::` usage, NAMESPACE, roxygen2, `@return`, `@examples`, export policy |
99| `surveycore-conventions.md` | Naming patterns (`get_*`, `extract_*`, `set_*`), `@family`, return visibility, haven handling |
100| `testing-standards.md` | `test_that()` scope, 98% coverage, assertion patterns, data generators |
101| `testing-surveycore.md` | `test_invariants()`, layer 1 vs layer 3 error testing, `make_survey_data()`, numerical tolerances |
102| `github-strategy.md` | Branch naming, PR granularity, commit format, merge strategy |
103
104---
105
106## File Locations
107
108The `{id}` matches the feature branch identifier (e.g., `phase-2`, `survey-srs`).
109
110```
111Implementation plan: plans/impl-{id}.md
112Plan review: plans/plan-review-{id}.md
113Decisions log: plans/decisions-{id}.md
114```
majiayu000