diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index cc1af1a5f..e51ad3d50 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -30,6 +30,17 @@ Start by understanding the current project context, then ask questions one at a - Cover: architecture, components, data flow, error handling, testing - Be ready to go back and clarify if something doesn't make sense +**Design for isolation and clarity:** +- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently +- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on? +- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work. +- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much. + +**Working in existing codebases:** +- Explore the current structure before proposing changes. Follow existing patterns. +- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in. +- Don't propose unrelated refactoring. Stay focused on what serves the current goal. + ## After the Design **Documentation:** diff --git a/skills/brainstorming/spec-document-reviewer-prompt.md b/skills/brainstorming/spec-document-reviewer-prompt.md index afc224ae3..6a97a17b2 100644 --- a/skills/brainstorming/spec-document-reviewer-prompt.md +++ b/skills/brainstorming/spec-document-reviewer-prompt.md @@ -23,6 +23,7 @@ Task tool (general-purpose): | Consistency | Internal contradictions, conflicting requirements | | Clarity | Ambiguous requirements | | YAGNI | Unrequested features, over-engineering | + | Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable | ## CRITICAL @@ -30,6 +31,7 @@ Task tool (general-purpose): - Any TODO markers or placeholder text - Sections saying "to be defined later" or "will spec when X is done" - Sections noticeably less detailed than others + - Units that lack clear boundaries or interfaces — can you understand what each unit does without reading its internals? ## Output Format diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 313588aaf..7cbe4a9a3 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -82,6 +82,39 @@ digraph process { } ``` +## Model Selection + +Use the least powerful model that can handle each role to conserve cost and increase speed. + +**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified. + +**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model. + +**Architecture, design, and review tasks**: use the most capable available model. + +**Task complexity signals:** +- Touches 1-2 files with a complete spec → cheap model +- Touches multiple files with integration concerns → standard model +- Requires design judgment or broad codebase understanding → most capable model + +## Handling Implementer Status + +Implementer subagents report one of four statuses. Handle each appropriately: + +**DONE:** Proceed to spec compliance review. + +**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review. + +**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch. + +**BLOCKED:** The implementer cannot complete the task. Assess the blocker: +1. If it's a context problem, provide more context and re-dispatch with the same model +2. If the task requires more reasoning, re-dispatch with a more capable model +3. If the task is too large, break it into smaller pieces +4. If the plan itself is wrong, escalate to the human + +**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change. + ## Prompt Templates - `./implementer-prompt.md` - Dispatch implementer subagent diff --git a/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/skills/subagent-driven-development/code-quality-reviewer-prompt.md index d029ea299..a04201ace 100644 --- a/skills/subagent-driven-development/code-quality-reviewer-prompt.md +++ b/skills/subagent-driven-development/code-quality-reviewer-prompt.md @@ -17,4 +17,10 @@ Task tool (superpowers:code-reviewer): DESCRIPTION: [task summary] ``` +**In addition to standard code quality concerns, the reviewer should check:** +- Does each file have one clear responsibility with a well-defined interface? +- Are units decomposed so they can be understood and tested independently? +- Is the implementation following the file structure from the plan? +- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.) + **Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md index db5404b30..400c10347 100644 --- a/skills/subagent-driven-development/implementer-prompt.md +++ b/skills/subagent-driven-development/implementer-prompt.md @@ -41,6 +41,36 @@ Task tool (general-purpose): **While you work:** If you encounter something unexpected or unclear, **ask questions**. It's always OK to pause and clarify. Don't guess or make assumptions. + ## Code Organization + + You reason best about code you can hold in context at once, and your edits are more + reliable when files are focused. Keep this in mind: + - Follow the file structure defined in the plan + - Each file should have one clear responsibility with a well-defined interface + - If a file you're creating is growing beyond the plan's intent, stop and report + it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance + - If an existing file you're modifying is already large or tangled, work carefully + and note it as a concern in your report + - In existing codebases, follow established patterns. Improve code you're touching + the way a good developer would, but don't restructure things outside your task. + + ## When You're in Over Your Head + + It is always OK to stop and say "this is too hard for me." Bad work is worse than + no work. You will not be penalized for escalating. + + **STOP and escalate when:** + - The task requires architectural decisions with multiple valid approaches + - You need to understand code beyond what was provided and can't find clarity + - You feel uncertain about whether your approach is correct + - The task involves restructuring existing code in ways the plan didn't anticipate + - You've been reading file after file trying to understand the system without progress + + **How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe + specifically what you're stuck on, what you've tried, and what kind of help you need. + The controller can provide more context, re-dispatch with a more capable model, + or break the task into smaller pieces. + ## Before Reporting Back: Self-Review Review your work with fresh eyes. Ask yourself: @@ -70,9 +100,14 @@ Task tool (general-purpose): ## Report Format When done, report: - - What you implemented + - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT + - What you implemented (or what you attempted, if blocked) - What you tested and test results - Files changed - Self-review findings (if any) - Any issues or concerns + + Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness. + Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need + information that wasn't provided. Never silently produce work you're unsure about. ``` diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 373a6e581..5ef80cd04 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -18,6 +18,17 @@ Assume they are a skilled developer, but know almost nothing about our toolset o **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-.md` - (User preferences for plan location override this default) +## File Structure + +Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in. + +- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility. +- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much. +- Files that change together should live together. Split by responsibility, not by technical layer. +- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable. + +This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently. + ## Bite-Sized Task Granularity **Each step is one action (2-5 minutes):** diff --git a/skills/writing-plans/plan-document-reviewer-prompt.md b/skills/writing-plans/plan-document-reviewer-prompt.md index 8def5a396..ce36cba13 100644 --- a/skills/writing-plans/plan-document-reviewer-prompt.md +++ b/skills/writing-plans/plan-document-reviewer-prompt.md @@ -22,6 +22,8 @@ Task tool (general-purpose): | Completeness | TODOs, placeholders, incomplete tasks, missing steps | | Spec Alignment | Chunk covers relevant spec requirements, no scope creep | | Task Decomposition | Tasks atomic, clear boundaries, steps actionable | + | File Structure | Files have clear single responsibilities, split by responsibility not layer | + | File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? | | Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking | | Chunk Size | Each chunk under 1000 lines | @@ -32,6 +34,7 @@ Task tool (general-purpose): - Steps that say "similar to X" without actual content - Incomplete task definitions - Missing verification steps or expected outputs + - Files planned to hold multiple responsibilities or likely to grow unwieldy ## Output Format