From b3dfcfed9267c454cbce3f6c640d1b2d34cf2800 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 5 Jul 2026 13:13:14 -0400 Subject: [PATCH] =?UTF-8?q?conductor(track):=20superpowers=20review=20sect?= =?UTF-8?q?ion=203=20=E2=80=94=20writing-plans=20(deep-dive)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../superpowers_review_20260619/report.md | 56 ++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/conductor/tracks/superpowers_review_20260619/report.md b/conductor/tracks/superpowers_review_20260619/report.md index 24e873ce..4fd675f9 100644 --- a/conductor/tracks/superpowers_review_20260619/report.md +++ b/conductor/tracks/superpowers_review_20260619/report.md @@ -128,7 +128,61 @@ The project follows the brainstorming discipline. The dual-convention question ( ## 3. Writing Plans - +## 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//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