diff --git a/conductor/tracks/superpowers_review_20260619/report.md b/conductor/tracks/superpowers_review_20260619/report.md index 881ff19e..24e873ce 100644 --- a/conductor/tracks/superpowers_review_20260619/report.md +++ b/conductor/tracks/superpowers_review_20260619/report.md @@ -60,7 +60,71 @@ The project follows the discipline. No code/spec changes recommended. The deferr ## 2. Brainstorming - +## 2. Brainstorming + +### 2.1 What the skill prescribes + +The `brainstorming` skill is the HARD-GATE entry point for any creative work. The skill's anti-pattern table is unambiguous: "This is too simple to need a design" is itself a design failure. The 9-step checklist is: + +1. Explore project context (files, docs, recent commits) +2. Offer visual companion (own message; only if visual questions ahead) +3. Ask clarifying questions (one at a time; multiple-choice preferred) +4. Propose 2-3 approaches with trade-offs +5. Present design in sections scaled to complexity; user approves each +6. Write design doc to `docs/superpowers/specs/YYYY-MM-DD--design.md` +7. Spec self-review (placeholder scan, internal consistency, scope check, ambiguity check) +8. User reviews the written spec +9. Invoke writing-plans skill (the only terminal state) + +The skill's process flow is a strict DAG with `writing-plans` as the only exit. It explicitly forbids jumping to `frontend-design`, `mcp-builder`, or any other implementation skill directly. + +### 2.2 Mapping to the project's existing pattern + +The project's spec convention is the conductor/track convention (`conductor/tracks//spec.md`), not the superpowers default (`docs/superpowers/specs/YYYY-MM-DD--design.md`). This is per user directive Q4 = A (see metadata.json `format_choice`). The structure of the project's specs is highly aligned with the brainstorming skill's requirements, though: + +| Brainstorming requirement | Project equivalent | Where | +|---|---|---| +| "Explore project context first" | Tier 1 Track Initialization Rules §"Audit Before Specifying" (per `conductor/workflow.md`) — mandatory `py_get_code_outline` + `py_find_usages` + `get_git_diff` before writing requirements | `conductor/workflow.md` §"Tier 1 Track Initialization Rules" | +| "Ask clarifying questions, one at a time" | The "Planning Session Workflow" in workflow.md §"Planning Session Workflow" prescribes brainstorming with multiple-choice preferred; the spec for *this* track was authored via such a dialogue | `conductor/workflow.md` §"Planning Session Workflow" | +| "Propose 2-3 approaches with trade-offs" | The "Propose 2-3 approaches" step is part of the brainstorming skill; the project's Tier 1 spec template §3 "Goals" includes "approach comparisons" implicitly via the priority-ordered goals | Spec template (this file's parent structure) | +| "Spec self-review" (placeholder scan, internal consistency, scope check, ambiguity check) | The Tier 1 Track Initialization Rules §1 "Spec format" mandates these checks; the workflow's "Phase Completion Verification and Checkpointing Protocol" includes self-review | `conductor/workflow.md` §"Tier 1 Track Initialization Rules" | +| "User reviews written spec before proceeding" | The "Planning Session Workflow" §5 explicitly says "User reviews the spec. Revise until approved. **The spec MUST be approved before the plan is written.** A plan for an unapproved spec is wasted effort." | `conductor/workflow.md` §"Planning Session Workflow" | +| "Invoke writing-plans as the only terminal state" | The workflow's "Planning Session Workflow" says "After spec approval, write plan following writing-plans skill" | `conductor/workflow.md` §"Planning Session Workflow" | + +### 2.3 Where the project already follows the brainstorming discipline + +- **All four sibling review tracks (`nagent_review_20260608`, `fable_review_20260617`, `intent_dsl_survey_20260612`, this track) followed the brainstorming discipline**: each has a spec.md with explicit "Current State Audit" sections citing file:line references, "Goals" sections in priority order, "Architecture Reference" sections linking to existing docs, and "Out of Scope" sections. This is the conductor convention's equivalent of the brainstorming checklist. +- **The `conductor/workflow.md` "Planning Session Workflow"** is itself a project-specific re-encoding of the brainstorming skill, with the conductor-specific twist that the spec is committed (per-file atomic) before the plan is written. +- **The "User reviews written spec before proceeding" gate** is enforced: every track on the project has spec + plan pairs that were user-approved (per the `tracks.md` rows with "spec ✓, plan ✓, ready to start" status). + +### 2.4 Where the project doesn't follow the discipline + +- **"Offer visual companion (own message)"** — not used. The project's brainstorming happens via inline text dialogue in the session, not via a separate browser-based message. This is a Claude Code feature (the visual companion is a browser-based UI); OpenCode does not have an equivalent. ARCH-DIFF: the project's text-only brainstorming is functionally equivalent for non-visual features but cannot mock up UI affordances interactively. +- **"Multiple-choice preferred"** — partially used. The `intent_dsl_survey_20260612/spec.md` §3.1 shows the project does use multiple-choice ("Use A / Use B / Use C" style questions), but this track's spec.md does not have visible multiple-choice answers; the questions are open-ended with the user picking the approach in their direct response. +- **"No jumping to implementation before spec approval"** — partially enforced. The workflow.md §"Task Workflow" starts with "Initialize MMA Environment" before "Select Task"; this presumes the spec is approved. But the project has had agents start coding in response to user requests without going through the spec-first pattern (e.g., quick fixes, follow-up tracks). The pattern is enforced for new tracks, not for one-off edits. +- **"Section self-review is 4 specific checks (placeholder, internal consistency, scope, ambiguity)"** — partially followed. The brainstorming skill's self-review is a 4-item checklist; the project's equivalent is the workflow's "Phase Completion Verification and Checkpointing Protocol" §2 which is more elaborate (5+ checks per phase). The project goes *deeper* than the skill here. +- **"Default location `docs/superpowers/specs/`"** — explicitly overridden by user choice. This is the dual-convention topic flagged in Section 16. + +### 2.5 Recommendations summary + +The project follows the brainstorming discipline. The dual-convention question (`docs/superpowers/specs/` vs `conductor/tracks//spec.md`) is the only major surface difference, and it's a user-chosen override. The deferred rebuild may want to: + +- **HIGH:** Add a "spec-first is mandatory for any creative work" prompt to the Session Start Checklist (item 13), explicitly calling out the "no jumping to implementation" rule. The project enforces this for new tracks; making it explicit for ad-hoc edits would close the partial-coverage gap. +- **MEDIUM:** Add a "multiple-choice preferred" guidance note to the spec template. The pattern exists in some specs; codifying it would reduce open-ended-question ambiguity. +- **LOW:** Consider adding a visual-companion equivalent for the next time the project does UI work. This is environmental (Claude Code feature), not a project-level change. + +**Verdict.** + +| Field | Value | +|---|---| +| **Primary** | `PARTIAL` | +| **Integration tag** | `INTEGRATE-PARTIAL` | +| **Section size** | deep-dive | +| **Cross-refs** | nagent_review_20260608 §3 (the durable-work thesis is the meta-design philosophy behind brainstorming); fable_review_20260617 §3 (Fable's product branding vs the project's "honest about gaps" approach); intent_dsl_survey_20260612 §1 (the survey was brainstormed using this discipline) | + +**Rationale.** The project's spec + plan + conductor/track convention is a faithful re-encoding of the brainstorming skill, with three gaps: (a) ad-hoc edits can skip the spec-first gate; (b) the "offer visual companion" rule is environmentally unavailable; (c) the multiple-choice preference is used inconsistently across specs. + +**Recommended change.** Add a "spec-first is mandatory for any creative work" prompt to the Session Start Checklist (item 13); add a "multiple-choice preferred" guidance note to the spec template; defer the visual-companion question to the deferred rebuild (it's an environment question, not a project question). ## 3. Writing Plans