oc

Signed-off-by: Christoph Schmatzler <christoph@schmatzler.com>

profiles/opencode/skill/spec-planner/references/decision-frameworks.md

@@ -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
+```

profiles/opencode/skill/spec-planner/references/estimation.md

@@ -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

profiles/opencode/skill/spec-planner/references/technical-debt.md

@@ -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

profiles/opencode/skill/spec-planner/references/templates.md

@@ -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.*
+```