conductor(track): superpowers review section 3 — writing-plans (deep-dive)

conductor/tracks/superpowers_review_20260619/report.md

@@ -128,7 +128,61 @@ The project follows the brainstorming discipline. The dual-convention question (
 
 ## 3. Writing Plans
 
-<!-- Section 3 deep-dive (200-400 LOC). Skill: writing-plans. Verdict pending. -->
+## 3. Writing Plans
+
+### 3.1 What the skill prescribes
+
+The `writing-plans` skill is the executable counterpart to brainstorming. It assumes the engineer has zero context for the codebase and questionable taste. The skill's bite-sized granularity rule is the load-bearing constraint: "Each step is one action (2-5 minutes)." A plan with vague steps ("implement the feature", "write tests", "add error handling") is a plan failure; the skill enumerates these as forbidden placeholder patterns. The plan header is mandatory (Goal / Architecture / Tech Stack), and the self-review is a 3-check inline pass: (1) spec coverage, (2) placeholder scan, (3) type consistency. The execution handoff offers two choices: subagent-driven (fresh subagent per task with two-stage review) or inline execution (batch with checkpoints).
+
+### 3.2 Mapping to the project's existing pattern
+
+The project's `conductor/workflow.md` §"Task Workflow" is a project-specific re-encoding of writing-plans, with 12 steps vs the skill's 5-step Task Structure template:
+
+| writing-plans element | Project equivalent | Where |
+|---|---|---|
+| Plan header (Goal, Architecture, Tech Stack) | Every `plan.md` has a header section (Goal + Architecture + Tech Stack + Spec reference + Blocked-by); see e.g. this track's `plan.md:3-16` | `conductor/tracks/<id>/plan.md` (universal) |
+| "Files: Create / Modify / Test" lists | The "Files" section in every Task N; exact paths always | Universal |
+| "Step 1: Write failing test" | "Step 4: Write Failing Tests (Red Phase)" — the "Pre-Delegation Checkpoint" sub-step adds a stage/commit rule | `conductor/workflow.md` §"Task Workflow" step 4 |
+| "Run it to make sure it fails" | "CRITICAL: Run the tests and confirm that they fail as expected. This is the 'Red' phase of TDD. Do not proceed until you have failing tests." | `conductor/workflow.md` §"Task Workflow" step 4 |
+| "Implement the minimal code to make the test pass" | "Implement to Pass Tests (Green Phase)" — also requires tier-3-worker delegation | `conductor/workflow.md` §"Task Workflow" step 5 |
+| "Commit" | "9. Commit Code Changes: CRITICAL - ATOMIC PER-TASK COMMITS" | `conductor/workflow.md` §"Task Workflow" step 9 |
+| "Self-Review" | "Phase Completion Verification and Checkpointing Protocol" — much more elaborate than the skill's 3-check self-review; includes automated tests, API hooks, user confirmation | `conductor/workflow.md` §"Phase Completion Verification" |
+| "Execution Handoff" | "Verify via API Hooks" + the live_gui fixture convention for integration tests | `conductor/workflow.md` §"Verification via API Hooks" |
+
+### 3.3 Where the project already follows the discipline
+
+- **Every track on the project has a plan.md with bite-sized steps.** Examples: `nagent_review_20260608/plan.md` (research-style plan with report sections as tasks), `fable_review_20260617/plan.md` (research-style plan with cluster sub-agent dispatches as tasks), `data_oriented_error_handling_20260606/plan.md` (refactor-style plan with audit-script updates as tasks). All three have tasks with concrete file:line references and verification steps.
+- **Per-file atomic commits + git notes.** This is the project's strict convention (`conductor/workflow.md` §"Task Workflow" step 9 + step 10); the writing-plans skill's "Commit" step is augmented with the "Attach Task Summary with Git Notes" step. The project goes *deeper* than the skill here.
+- **"No placeholders" rule.** The workflow.md's "Plan format" section explicitly bans vague tasks; the project's plans are uniformly bite-sized. The skill's forbidden patterns ("TBD", "TODO", "implement later", "fill in details") are also forbidden in the project.
+- **The "exact file paths always" rule** is enforced; every plan task lists exact file:line references (e.g., this track's plan.md §"Phase 2 Task 5" cites `C:\Users\Ed\.cache\opencode\packages\superpowers@git+https_\github.com\obra\superpowers.git\node_modules\superpowers\skills\brainstorming\SKILL.md`).
+- **The "DRY, YAGNI, TDD, frequent commits" maxims** are present in both skill and project; the project's added maxims are "1-space indentation" and "no day estimates" (per `conductor/workflow.md` §"Code Style" + §"Tier 1 Track Initialization Rules").
+
+### 3.4 Where the project doesn't follow the discipline
+
+- **The skill's "Subagent-Driven (recommended)" execution path** is NOT the project's default. The project's tier model is hierarchical (4 tiers: orchestrator, tech-lead, worker, qa) and the tier-3-worker dispatch is via OpenCode Task tool (per `conductor/workflow.md` §"Conductor Token Firewalling"). The skill's "fresh subagent per task" pattern is the tier-3-worker pattern; the project's tier-2 tech-lead maintains persistent context. This is ARCH-DIFF (architectural difference): the project uses a more elaborate hierarchy than the skill's flat 2-option menu.
+- **"Visual Companion offer (own message)"** — not applicable to plan-writing (it's a brainstorming skill, not a writing-plans skill).
+- **The skill's "subagent-driven" recommendation requires a subagent-capable platform.** The project's tier-3 workers run via OpenCode's subagent system; not all environments have this. The project's tier-2 in-line execution path is the fallback; the skill's "inline execution" is the fallback too, but the project lacks the skill's "two-stage review" between subagent and continuation (the project uses Tier 4 QA agents for failure analysis).
+- **The "Code Style: 1-space indentation for Python" reminder** is in the project's tier-3-worker dispatch prompt per `conductor/workflow.md` §"Task Workflow" step 4 + step 5 ("ALWAYS explicitly mention 'Use exactly 1-space indentation for Python code' when prompting a sub-agent"). The skill does not have this — Python-style is environment-specific.
+
+### 3.5 Recommendations summary
+
+The project follows the discipline with one architectural difference (4-tier hierarchy vs 2-option menu) and three elaborations (per-file atomic commits + git notes; "no day estimates"; "1-space indentation" reminder for tier-3 workers). The deferred rebuild may want to:
+
+- **LOW:** Add a note to `conductor/workflow.md` §"Task Workflow" that the "Subagent-Driven" option maps to "Tier 3 worker per task + Tier 4 QA on failure" (the project's tiered equivalent). This is a naming-bridge, not a behavior change.
+- **LOW:** Codify the "1-space indentation" reminder in a tier-3-worker dispatcher template (`.agents/skills/mma-tier3-worker/SKILL.md` already has this as a hard rule per the skill content). Currently the reminder is in workflow.md + dispatch prompt, not in the skill itself. The deferred rebuild could move it.
+
+**Verdict.**
+
+| Field | Value |
+|---|---|
+| **Primary** | `PARITY` |
+| **Integration tag** | `INTEGRATED` |
+| **Section size** | deep-dive |
+| **Cross-refs** | nagent_review_20260608 §3 (the durable-work thesis shapes how plans are written — bite-sized, atomic, recoverable); fable_review_20260617 §3 (the cluster-sub-agent dispatch pattern is a writing-plans innovation the project already uses for research tracks); intent_dsl_survey_20260612 §3 (the survey plan uses tier-3-worker dispatches for cluster research, mirroring the skill's subagent-driven option) |
+
+**Rationale.** The project's 12-step task workflow is a faithful elaboration of writing-plans. Every required element (header, Files section, bite-sized steps, self-review, no placeholders) is present. The architectural difference (4-tier hierarchy vs 2-option menu) is a project-specific design that subsumes the skill's option; the project uses tier-3 workers (the skill's subagent option) plus tier-4 QA (extra) plus tier-2 persistent context (extra).
+
+**Recommended change.** *(blank — no rebuild action. The project is in alignment.)*
 
 ## 4. Test-Driven Development