206
profiles/opencode/skill/spec-planner/SKILL.md
Normal file
206
profiles/opencode/skill/spec-planner/SKILL.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
name: spec-planner
|
||||
description: Dialogue-driven spec development through skeptical questioning and iterative refinement. Triggers: "spec this out", feature planning, architecture decisions, "is this worth it?" questions, RFC/design doc creation, work scoping. Invoke Librarian for unfamiliar tech/frameworks/APIs.
|
||||
---
|
||||
|
||||
# Spec Planner
|
||||
|
||||
Produce implementation-ready specs through rigorous dialogue and honest trade-off analysis.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Dialogue over deliverables** - Plans emerge from discussion, not assumption
|
||||
- **Skeptical by default** - Requirements are incomplete until proven otherwise
|
||||
- **Second-order thinking** - Consider downstream effects and maintenance burden
|
||||
|
||||
## Workflow Phases
|
||||
|
||||
```
|
||||
CLARIFY --[user responds]--> DISCOVER --[done]--> DRAFT --[complete]--> REFINE --[approved]--> DONE
|
||||
| | | |
|
||||
+--[still ambiguous]--<------+-------------------+----[gaps found]------+
|
||||
```
|
||||
|
||||
**State phase at end of every response:**
|
||||
```
|
||||
---
|
||||
Phase: CLARIFY | Waiting for: answers to questions 1-4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: CLARIFY (Mandatory)
|
||||
|
||||
**Hard rule:** No spec until user has responded to at least one round of questions.
|
||||
|
||||
1. **STOP.** Do not proceed to planning.
|
||||
2. Identify gaps in: scope, motivation, constraints, edge cases, success criteria
|
||||
3. Ask 3-5 pointed questions that would change the approach. USE YOUR QUESTION TOOL.
|
||||
4. **Wait for responses**
|
||||
|
||||
| Category | Example |
|
||||
|----------|---------|
|
||||
| Scope | "Share where? Social media? Direct link? Embed?" |
|
||||
| Motivation | "What user problem are we actually solving?" |
|
||||
| Constraints | "Does this need to work with existing privacy settings?" |
|
||||
| Success | "How will we know this worked?" |
|
||||
|
||||
**Escape prevention:** Even if request seems complete, ask 2+ clarifying questions. Skip only for mechanical requests (e.g., "rename X to Y").
|
||||
|
||||
**Anti-patterns to resist:**
|
||||
- "Just give me a rough plan" -> Still needs scope questions
|
||||
- "I'll figure out the details" -> Those details ARE the spec
|
||||
- Very long initial request -> Longer != clearer; probe assumptions
|
||||
|
||||
**Transition:** User answered AND no new ambiguities -> DISCOVER
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: DISCOVER
|
||||
|
||||
**After clarification, before planning:** Understand existing system.
|
||||
|
||||
Launch explore subagents in parallel:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="explore",
|
||||
description="Explore [area name]",
|
||||
prompt="Explore [area]. Return: key files, abstractions, patterns, integration points."
|
||||
)
|
||||
```
|
||||
|
||||
| Target | What to Find |
|
||||
|--------|--------------|
|
||||
| Affected area | Files, modules that will change |
|
||||
| Existing patterns | How similar features are implemented |
|
||||
| Integration points | APIs, events, data flows touched |
|
||||
|
||||
**If unfamiliar tech involved**, invoke Librarian:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="librarian",
|
||||
description="Research [tech name]",
|
||||
prompt="Research [tech] for [use case]. Return: recommended approach, gotchas, production patterns."
|
||||
)
|
||||
```
|
||||
|
||||
**Output:** Brief architecture summary before proposing solutions.
|
||||
|
||||
**Transition:** System context understood -> DRAFT
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: DRAFT
|
||||
|
||||
Apply planning framework from [decision-frameworks.md](./references/decision-frameworks.md):
|
||||
|
||||
1. **Problem Definition** - What are we solving? For whom? Cost of not solving?
|
||||
2. **Constraints Inventory** - Time, system, knowledge, scope ceiling
|
||||
3. **Solution Space** - Simplest -> Balanced -> Full engineering solution
|
||||
4. **Trade-off Analysis** - See table format in references
|
||||
5. **Recommendation** - One clear choice with reasoning
|
||||
|
||||
Use appropriate template from [templates.md](./references/templates.md):
|
||||
- **Quick Decision** - Scoped technical choices
|
||||
- **Feature Plan** - New feature development
|
||||
- **ADR** - Architecture decisions
|
||||
- **RFC** - Larger proposals
|
||||
|
||||
**Transition:** Spec produced -> REFINE
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: REFINE
|
||||
|
||||
Run completeness check:
|
||||
|
||||
| Criterion | Check |
|
||||
|-----------|-------|
|
||||
| Scope bounded | Every deliverable listed; non-goals explicit |
|
||||
| Ambiguity resolved | No "TBD" or "to be determined" |
|
||||
| Acceptance testable | Each criterion pass/fail verifiable |
|
||||
| Dependencies ordered | Clear what blocks what |
|
||||
| Types defined | Data shapes specified (not "some object") |
|
||||
| Effort estimated | Each deliverable has S/M/L/XL |
|
||||
| Risks identified | At least 2 risks with mitigations |
|
||||
| Open questions | Resolved OR assigned owner |
|
||||
|
||||
**If any criterion fails:** Return to dialogue. "To finalize, I need clarity on: [failing criteria]."
|
||||
|
||||
**Transition:** All criteria pass + user approval -> DONE
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: DONE
|
||||
|
||||
### Final Output
|
||||
|
||||
```
|
||||
=== Spec Complete ===
|
||||
|
||||
Phase: DONE
|
||||
Type: <feature plan | architecture decision | refactoring | strategy>
|
||||
Effort: <S/M/L/XL>
|
||||
Status: Ready for task breakdown
|
||||
|
||||
Discovery:
|
||||
- Explored: <areas investigated>
|
||||
- Key findings: <relevant architecture/patterns>
|
||||
|
||||
Recommendation:
|
||||
<brief summary>
|
||||
|
||||
Key Trade-offs:
|
||||
- <what we're choosing vs alternatives>
|
||||
|
||||
Deliverables (Ordered):
|
||||
1. [D1] (effort) - depends on: -
|
||||
2. [D2] (effort) - depends on: D1
|
||||
|
||||
Open Questions:
|
||||
- [ ] <if any remain> -> Owner: [who]
|
||||
```
|
||||
|
||||
### Write Spec to File (MANDATORY)
|
||||
|
||||
1. Derive filename from feature/decision name (kebab-case)
|
||||
2. Write spec to `specs/<filename>.md`
|
||||
3. Confirm: `Spec written to: specs/<filename>.md`
|
||||
|
||||
---
|
||||
|
||||
## Effort Estimates
|
||||
|
||||
| Size | Time | Scope |
|
||||
|------|------|-------|
|
||||
| **S** | <1 hour | Single file, isolated change |
|
||||
| **M** | 1-3 hours | Few files, contained feature |
|
||||
| **L** | 1-2 days | Cross-cutting, multiple components |
|
||||
| **XL** | >2 days | Major refactor, new system |
|
||||
|
||||
## Scope Control
|
||||
|
||||
When scope creeps:
|
||||
1. **Name it:** "That's scope expansion. Let's finish X first."
|
||||
2. **Park it:** "Added to Open Questions. Revisit after core spec stable."
|
||||
3. **Cost it:** "Adding Y changes effort from M to XL. Worth it?"
|
||||
|
||||
**Hard rule:** If scope changes, re-estimate and flag explicitly.
|
||||
|
||||
## References
|
||||
|
||||
| File | When to Read |
|
||||
|------|--------------|
|
||||
| [templates.md](./references/templates.md) | Output formats for plans, ADRs, RFCs |
|
||||
| [decision-frameworks.md](./references/decision-frameworks.md) | Complex multi-factor decisions |
|
||||
| [estimation.md](./references/estimation.md) | Breaking down work, avoiding underestimation |
|
||||
| [technical-debt.md](./references/technical-debt.md) | Evaluating refactoring ROI |
|
||||
|
||||
## Integration
|
||||
|
||||
| Agent | When to Invoke |
|
||||
|-------|----------------|
|
||||
| **Librarian** | Research unfamiliar tech, APIs, frameworks |
|
||||
| **Oracle** | Deep architectural analysis, complex debugging |
|
||||
@@ -0,0 +1,75 @@
|
||||
# Decision Frameworks
|
||||
|
||||
## Reversibility Matrix
|
||||
|
||||
| Decision Type | Approach |
|
||||
|---------------|----------|
|
||||
| **Two-way door** (easily reversed) | Decide fast, learn from outcome |
|
||||
| **One-way door** (hard to reverse) | Invest time in analysis |
|
||||
|
||||
Most decisions are two-way doors. Don't over-analyze.
|
||||
|
||||
## Cost of Delay
|
||||
|
||||
```
|
||||
Daily Cost = (Value Delivered / Time to Deliver) x Risk Factor
|
||||
```
|
||||
|
||||
Use when prioritizing:
|
||||
- High daily cost -> Do first
|
||||
- Low daily cost -> Can wait
|
||||
|
||||
## RICE Scoring
|
||||
|
||||
| Factor | Question | Scale |
|
||||
|--------|----------|-------|
|
||||
| **R**each | How many users affected? | # users/period |
|
||||
| **I**mpact | How much per user? | 0.25, 0.5, 1, 2, 3 |
|
||||
| **C**onfidence | How sure are we? | 20%, 50%, 80%, 100% |
|
||||
| **E**ffort | Person-weeks | 0.5, 1, 2, 4, 8+ |
|
||||
|
||||
```
|
||||
RICE = (Reach x Impact x Confidence) / Effort
|
||||
```
|
||||
|
||||
## Technical Decision Checklist
|
||||
|
||||
Before committing to a technical approach:
|
||||
|
||||
- [ ] Have we talked to someone who's done this before?
|
||||
- [ ] What's the simplest version that teaches us something?
|
||||
- [ ] What would make us reverse this decision?
|
||||
- [ ] Who maintains this in 6 months?
|
||||
- [ ] What's our rollback plan?
|
||||
|
||||
## When to Build vs Buy vs Adopt
|
||||
|
||||
| Signal | Build | Buy | Adopt (OSS) |
|
||||
|--------|-------|-----|-------------|
|
||||
| Core differentiator | Yes | No | Maybe |
|
||||
| Commodity problem | No | Yes | Yes |
|
||||
| Tight integration needed | Yes | Maybe | Maybe |
|
||||
| Team has expertise | Yes | N/A | Yes |
|
||||
| Time pressure | No | Yes | Maybe |
|
||||
| Long-term control needed | Yes | No | Maybe |
|
||||
|
||||
## Decomposition Strategies
|
||||
|
||||
### Vertical Slicing
|
||||
Cut features into thin end-to-end slices that deliver value:
|
||||
```
|
||||
Bad: "Build database layer" -> "Build API" -> "Build UI"
|
||||
Good: "User can see their profile" -> "User can edit name" -> "User can upload avatar"
|
||||
```
|
||||
|
||||
### Risk-First Ordering
|
||||
1. Identify highest-risk unknowns
|
||||
2. Build spike/proof-of-concept for those first
|
||||
3. Then build around proven foundation
|
||||
|
||||
### Dependency Mapping
|
||||
```
|
||||
[Feature A] -depends on-> [Feature B] -depends on-> [Feature C]
|
||||
^
|
||||
Start here
|
||||
```
|
||||
@@ -0,0 +1,69 @@
|
||||
# Estimation
|
||||
|
||||
## Why Estimates Fail
|
||||
|
||||
| Cause | Mitigation |
|
||||
|-------|------------|
|
||||
| Optimism bias | Use historical data, not gut |
|
||||
| Missing scope | List "obvious" tasks explicitly |
|
||||
| Integration blindness | Add 20-30% for glue code |
|
||||
| Unknown unknowns | Add buffer based on novelty |
|
||||
| Interruptions | Assume 60% focused time |
|
||||
|
||||
## Estimation Techniques
|
||||
|
||||
### Three-Point Estimation
|
||||
```
|
||||
Expected = (Optimistic + 4xMostLikely + Pessimistic) / 6
|
||||
```
|
||||
|
||||
### Relative Sizing
|
||||
Compare to known references:
|
||||
- "This is about twice as complex as Feature X"
|
||||
- Use Fibonacci (1, 2, 3, 5, 8, 13) to reflect uncertainty
|
||||
|
||||
### Task Decomposition
|
||||
1. Break into tasks <=4 hours
|
||||
2. If can't decompose, spike first
|
||||
3. Sum tasks + 20% integration buffer
|
||||
|
||||
## Effort Multipliers
|
||||
|
||||
| Factor | Multiplier |
|
||||
|--------|------------|
|
||||
| New technology | 1.5-2x |
|
||||
| Unclear requirements | 1.3-1.5x |
|
||||
| External dependencies (waiting on others) | 1.2-1.5x |
|
||||
| Legacy/undocumented code | 1.3-2x |
|
||||
| Production deployment | 1.2x |
|
||||
| First time doing X | 2-3x |
|
||||
| Context switching (other priorities) | 1.3x |
|
||||
| Yak shaving risk (unknown unknowns) | 1.5x |
|
||||
|
||||
## Hidden Work Checklist
|
||||
|
||||
Always include time for:
|
||||
- [ ] Code review (20% of dev time)
|
||||
- [ ] Testing (30-50% of dev time)
|
||||
- [ ] Documentation (10% of dev time)
|
||||
- [ ] Deployment/config (varies)
|
||||
- [ ] Bug fixes from testing (20% buffer)
|
||||
- [ ] Interruptions / competing priorities
|
||||
|
||||
## When to Re-Estimate
|
||||
|
||||
Re-estimate when:
|
||||
- Scope changes materially
|
||||
- Major unknown becomes known
|
||||
- Actual progress diverges >30% from estimate
|
||||
|
||||
## Communicating Estimates
|
||||
|
||||
**Good:** "1-2 weeks, confidence 70%-main risk is the third-party API integration"
|
||||
|
||||
**Bad:** "About 2 weeks"
|
||||
|
||||
Always include:
|
||||
1. Range, not point estimate
|
||||
2. Confidence level
|
||||
3. Key assumptions/risks
|
||||
@@ -0,0 +1,94 @@
|
||||
# Technical Debt
|
||||
|
||||
## Debt Categories
|
||||
|
||||
| Type | Example | Urgency |
|
||||
|------|---------|---------|
|
||||
| **Deliberate-Prudent** | "Ship now, refactor next sprint" | Planned paydown |
|
||||
| **Deliberate-Reckless** | "We don't have time for tests" | Accumulating risk |
|
||||
| **Inadvertent-Prudent** | "Now we know a better way" | Normal learning |
|
||||
| **Inadvertent-Reckless** | "What's layering?" | Learning curve |
|
||||
|
||||
## When to Pay Down Debt
|
||||
|
||||
**Pay now when:**
|
||||
- Debt is in path of upcoming work
|
||||
- Cognitive load slowing every change
|
||||
- Bugs recurring in same area
|
||||
- Onboarding time increasing
|
||||
|
||||
**Defer when:**
|
||||
- Area is stable, rarely touched
|
||||
- Bigger refactor coming anyway
|
||||
- Time constrained on priority work
|
||||
- Code may be deprecated
|
||||
|
||||
## ROI Framework
|
||||
|
||||
```
|
||||
Debt ROI = (Time Saved Per Touch x Touches/Month x Months) / Paydown Cost
|
||||
```
|
||||
|
||||
| ROI | Action |
|
||||
|-----|--------|
|
||||
| >3x | Prioritize immediately |
|
||||
| 1-3x | Plan into upcoming work |
|
||||
| <1x | Accept or isolate |
|
||||
|
||||
## Refactoring Strategies
|
||||
|
||||
### Strangler Fig
|
||||
1. Build new alongside old
|
||||
2. Redirect traffic incrementally
|
||||
3. Remove old when empty
|
||||
|
||||
Best for: Large system replacements
|
||||
|
||||
### Branch by Abstraction
|
||||
1. Create abstraction over old code
|
||||
2. Implement new behind abstraction
|
||||
3. Switch implementations
|
||||
4. Remove old
|
||||
|
||||
Best for: Library/dependency swaps
|
||||
|
||||
### Parallel Change (Expand-Contract)
|
||||
1. Add new behavior alongside old
|
||||
2. Migrate callers incrementally
|
||||
3. Remove old behavior
|
||||
|
||||
Best for: API changes
|
||||
|
||||
### Mikado Method
|
||||
1. Try the change
|
||||
2. When it breaks, note prerequisites
|
||||
3. Revert
|
||||
4. Recursively fix prerequisites
|
||||
5. Apply original change
|
||||
|
||||
Best for: Untangling dependencies
|
||||
|
||||
## Tracking Debt
|
||||
|
||||
Minimum viable debt tracking:
|
||||
```markdown
|
||||
## Tech Debt Log
|
||||
|
||||
| ID | Description | Impact | Area | Added |
|
||||
|----|-------------|--------|------|-------|
|
||||
| TD-1 | No caching layer | Slow queries | /api | 2024-01 |
|
||||
```
|
||||
|
||||
Review monthly. Prune resolved items.
|
||||
|
||||
## Communicating Debt to Stakeholders
|
||||
|
||||
**Frame as investment, not cleanup:**
|
||||
- "This will reduce bug rate by ~30%"
|
||||
- "Deployment time goes from 2 hours to 20 minutes"
|
||||
- "New features in this area take 2x longer than they should"
|
||||
|
||||
**Avoid:**
|
||||
- "The code is messy"
|
||||
- "We need to refactor"
|
||||
- Technical jargon without business impact
|
||||
161
profiles/opencode/skill/spec-planner/references/templates.md
Normal file
161
profiles/opencode/skill/spec-planner/references/templates.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Output Templates
|
||||
|
||||
## Quick Decision
|
||||
|
||||
For scoped technical choices with clear options.
|
||||
|
||||
```
|
||||
## Decision: [choice]
|
||||
|
||||
**Why:** [1-2 sentences]
|
||||
**Trade-off:** [what we're giving up]
|
||||
**Revisit if:** [trigger conditions]
|
||||
```
|
||||
|
||||
## Feature Plan (Implementation-Ready)
|
||||
|
||||
For new feature development. **Complete enough for task decomposition.**
|
||||
|
||||
```
|
||||
## Feature: [name]
|
||||
|
||||
### Problem Statement
|
||||
**Who:** [specific user/persona]
|
||||
**What:** [the problem they face]
|
||||
**Why it matters:** [business/user impact]
|
||||
**Evidence:** [how we know this is real]
|
||||
|
||||
### Proposed Solution
|
||||
[High-level approach in 2-3 paragraphs]
|
||||
|
||||
### Scope & Deliverables
|
||||
| Deliverable | Effort | Depends On |
|
||||
|-------------|--------|------------|
|
||||
| [D1] | S/M/L | - |
|
||||
| [D2] | S/M/L | D1 |
|
||||
|
||||
### Non-Goals (Explicit Exclusions)
|
||||
- [Thing people might assume is in scope but isn't]
|
||||
|
||||
### Data Model
|
||||
[Types, schemas, state shapes that will exist or change]
|
||||
|
||||
### API/Interface Contract
|
||||
[Public interfaces between components-input/output/errors]
|
||||
|
||||
### Acceptance Criteria
|
||||
- [ ] [Testable statement 1]
|
||||
- [ ] [Testable statement 2]
|
||||
|
||||
### Test Strategy
|
||||
| Layer | What | How |
|
||||
|-------|------|-----|
|
||||
| Unit | [specific logic] | [approach] |
|
||||
| Integration | [boundaries] | [approach] |
|
||||
|
||||
### Risks & Mitigations
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
|
||||
### Trade-offs Made
|
||||
| Chose | Over | Because |
|
||||
|-------|------|---------|
|
||||
|
||||
### Open Questions
|
||||
- [ ] [Question] -> Owner: [who decides]
|
||||
|
||||
### Success Metrics
|
||||
- [Measurable outcome]
|
||||
```
|
||||
|
||||
## Architecture Decision Record (ADR)
|
||||
|
||||
For significant architecture decisions that need documentation.
|
||||
|
||||
```
|
||||
## ADR: [title]
|
||||
|
||||
**Status:** Proposed | Accepted | Deprecated | Superseded
|
||||
**Date:** [date]
|
||||
|
||||
### Context
|
||||
[What forces are at play]
|
||||
|
||||
### Decision
|
||||
[What we're doing]
|
||||
|
||||
### Consequences
|
||||
- [+] [Benefit]
|
||||
- [-] [Drawback]
|
||||
- [~] [Neutral observation]
|
||||
```
|
||||
|
||||
## RFC (Request for Comments)
|
||||
|
||||
For larger proposals needing broader review.
|
||||
|
||||
```
|
||||
## RFC: [title]
|
||||
|
||||
**Author:** [name]
|
||||
**Status:** Draft | In Review | Accepted | Rejected
|
||||
**Created:** [date]
|
||||
|
||||
### Summary
|
||||
[1-2 paragraph overview]
|
||||
|
||||
### Motivation
|
||||
[Why are we doing this?]
|
||||
|
||||
### Detailed Design
|
||||
[Technical details]
|
||||
|
||||
### Alternatives Considered
|
||||
| Option | Pros | Cons | Why Not |
|
||||
|--------|------|------|---------|
|
||||
|
||||
### Migration/Rollout
|
||||
[How we get from here to there]
|
||||
|
||||
### Open Questions
|
||||
- [ ] [Question]
|
||||
```
|
||||
|
||||
## Handoff Artifact
|
||||
|
||||
When spec is complete, produce final summary for task decomposition:
|
||||
|
||||
```
|
||||
# [Feature Name] - Implementation Spec
|
||||
|
||||
**Status:** Ready for task breakdown
|
||||
**Effort:** [total estimate]
|
||||
**Approved by:** [human who approved]
|
||||
**Date:** [date]
|
||||
|
||||
## Deliverables (Ordered)
|
||||
|
||||
1. **[D1]** (S) - [one-line description]
|
||||
- Depends on: -
|
||||
- Files likely touched: [paths]
|
||||
|
||||
2. **[D2]** (M) - [one-line description]
|
||||
- Depends on: D1
|
||||
- Files likely touched: [paths]
|
||||
|
||||
## Key Technical Decisions
|
||||
- [Decision]: [choice] because [reason]
|
||||
|
||||
## Data Model
|
||||
[Copy from spec]
|
||||
|
||||
## Acceptance Criteria
|
||||
1. [Criterion 1]
|
||||
2. [Criterion 2]
|
||||
|
||||
## Open Items (Non-Blocking)
|
||||
- [Item] -> Owner: [who]
|
||||
|
||||
---
|
||||
*Spec approved for task decomposition.*
|
||||
```
|
||||
Reference in New Issue
Block a user