diff --git a/skills/approach/README.md b/skills/approach/README.md new file mode 100644 index 0000000..0c4c7b0 --- /dev/null +++ b/skills/approach/README.md @@ -0,0 +1,26 @@ +# Approach Skill + +Define the **How** and the **Strategy**. + +This is the second step in the **Intent → Approach → Work** triad. It maps the problem (Intent) to a solution architecture before committing to code. + +## Philosophy + +A list of tasks without a strategy is just noise. Approach forces you to make the hard decisions - trade-offs, architecture, blast radius - before you start coding. + +## When to Use + +- Intent is defined and confirmed +- User asks "How should we build this?" +- Before breaking work into tasks + +## The Process + +1. **Analyze the Intent** - Read `docs/intent/*.md`, identify the hard parts +2. **Define the Strategy** - Architecture, trade-offs, risks +3. **Document** - Create `docs/approach/-.md` +4. **Confirm** - Review with user before proceeding to Work + +## Output + +An **Approach Document** that guides the Work phase. High-level strategy, not step-by-step tasks. diff --git a/skills/approach/SKILL.md b/skills/approach/SKILL.md new file mode 100644 index 0000000..60daafc --- /dev/null +++ b/skills/approach/SKILL.md @@ -0,0 +1,70 @@ +--- +name: approach +description: Define the "How" and "Strategy". Use after Intent is defined. Focuses on architecture, trade-offs, and risks rather than linear task lists. +--- + +# Approach (The Strategy) + +## Philosophy + +You are not a "Planner." You are a **Strategist**. + +Linear task lists are optimistic fantasies. Approach is a battle plan that anticipates friction, identifies risks, and makes trade-offs explicit. + +## When to Use + +- User asks "How do we build this?" +- An **Intent** document has been approved +- Before breaking down into executable tasks + +## The Process + +1. **Analyze the Intent**: + - Read the relevant `docs/intent/*.md` + - Identify the technical hard parts + - What could go wrong? + +2. **Define the Strategy**: + - **Architecture**: What components change? + - **Trade-offs**: What are we sacrificing? (Speed vs safety? Simplicity vs completeness?) + - **Blast Radius**: What might we break? + +3. **Draft the Approach Document**: + - Create file: `docs/approach/-.md` + - Use the template below. + +4. **Confirm with User**: + - Review the strategy before proceeding to Work. + +## The Template + +```markdown +# Approach: [Title] + +## Strategy +The core technical philosophy for this work. + +**Key Decisions**: +- Decision 1: [Option A vs Option B] → [Choice] because [Reason] +- Decision 2: [...] + +## Architecture +- **New Components**: [List] +- **Modified Components**: [List] +- **Data Model Changes**: [If any] + +## Risks +- **Known Unknowns**: What are we unsure about? +- **Failure Modes**: How could this break? +- **Blast Radius**: What else might be affected? + +## Phases (High Level) +1. **Phase 1**: [Theme/goal] +2. **Phase 2**: [Theme/goal] +``` + +## Rules + +- **No Step-by-Step Tasks**: Don't write "Step 1: Create file X". That belongs in **Work**. +- **Stay High-Level**: Approach maps Intent to Work. It's strategy, not tactics. +- **Make Trade-offs Explicit**: Every decision has a cost. Name it. diff --git a/skills/intent/README.md b/skills/intent/README.md new file mode 100644 index 0000000..bcf10dd --- /dev/null +++ b/skills/intent/README.md @@ -0,0 +1,36 @@ +# Intent Skill + +Capture the **Why** before the **How**. + +This is the first step in the **Intent → Approach → Work** triad. It ensures you understand the motivation, need, and use-cases deeply before jumping to solutions. + +## Philosophy + +Most projects fail because the intent was misunderstood, not because the code was bad. This skill creates a deliberate pause: interrogate the request until you have enough context to proceed confidently. + +## When to Use + +- Starting a new feature or project +- Vague or open-ended requests +- User says "I want to build X" without explaining why +- Before any significant implementation work + +## The Process + +1. **Interrogate** - Ask clarifying questions until you understand: + - What problem are we solving? + - Who has this problem? When? + - What does success look like? + - What are the constraints and non-goals? + +2. **Document** - Create `docs/intent/-.md` with: + - Motivation (why this matters) + - Need (the underlying problem) + - Use-cases (concrete scenarios) + - Constraints and anti-goals + +3. **Confirm** - Review with user before proceeding to Approach + +## Output + +An **Intent Document** that serves as the foundation for the Approach phase. No implementation details - stay in the problem space. diff --git a/skills/intent/SKILL.md b/skills/intent/SKILL.md new file mode 100644 index 0000000..bcb6509 --- /dev/null +++ b/skills/intent/SKILL.md @@ -0,0 +1,68 @@ +--- +name: intent +description: Capture the "Why" behind a request. Use when starting new features or vague tasks. Interrogate until you understand motivation, need, and use-cases deeply. +--- + +# Intent (The Why) + +## Philosophy + +You are not a "Requirements Gatherer." You are an **Intent Analyst**. + +Your job is to interrogate the request until you deeply understand the motivation, need, and use-cases. Don't infer - ask. + +## When to Use + +- User says "I want to build X" +- User says "Let's start a new feature" +- User has a vague idea +- Before any significant implementation work + +## The Process + +1. **Interrogate the Request**: + - What problem are we solving? + - Who has this problem? When does it occur? + - What does success look like? + - What are the constraints? + - What are we explicitly NOT doing? + +2. **Draft the Intent Document**: + - Create file: `docs/intent/-.md` + - Use the template below. + +3. **Confirm with User**: + - "Does this capture the intent?" + - Iterate until they say yes. + +## The Template + +```markdown +# Intent: [Title] + +## Motivation +Why does this matter? What's driving the request? + +## Need +The underlying problem we're solving. + +## Use-Cases +Concrete scenarios where this problem occurs: +- Scenario 1: [Who, what, when, why it's painful] +- Scenario 2: [...] + +## Success Criteria +What does "done" look like? How will we know it's working? + +## Constraints +Hard limits we must work within. + +## Anti-Goals +What are we explicitly NOT doing? (Crucial for scope) +``` + +## Rules + +- **No Implementation Details**: If you find yourself writing "Use React" or "Create class X", STOP. That belongs in **Approach**. +- **Stay in Problem Space**: Intent describes the problem. Approach describes the solution. +- **Ask, Don't Assume**: If you're unsure, ask another clarifying question. diff --git a/skills/work/README.md b/skills/work/README.md new file mode 100644 index 0000000..340d6ec --- /dev/null +++ b/skills/work/README.md @@ -0,0 +1,26 @@ +# Work Skill + +Execute the **Do** with verification. + +This is the final step in the **Intent → Approach → Work** triad. It breaks strategy into atomic, verifiable units of work. + +## Philosophy + +Ideas are cheap. Execution is everything. Work is not about checking boxes - it's about producing **evidence**. Every unit of work must be verified before marking complete. + +## When to Use + +- Approach is defined and confirmed +- Ready to start implementation +- Breaking down strategy into executable tasks + +## The Process + +1. **Decompose** - Break Approach into atomic, verifiable units +2. **Execute** - Implement one unit at a time +3. **Verify** - Run the verification command, capture evidence +4. **Record** - Mark complete only after verification passes + +## Output + +A **Work Document** in `docs/work/` with a checklist, verification commands, and an audit trail of evidence. diff --git a/skills/work/SKILL.md b/skills/work/SKILL.md new file mode 100644 index 0000000..f626bc0 --- /dev/null +++ b/skills/work/SKILL.md @@ -0,0 +1,111 @@ +--- +name: work +description: Execute the "Do". Use after Approach is defined. Break down strategy into atomic, verifiable units. Enforces verification before marking complete. +--- + +# Work (The Execution) + +## Philosophy + +You are not just "doing tasks." You are producing **evidence of progress**. + +**The Iron Law**: If it isn't verified, it isn't done. It's just typing. + +## When to Use + +- User says "Implement this" +- User says "Let's start coding" +- An **Approach** document is ready + +## The Process + +1. **Decompose the Approach**: + - Break strategy into atomic, verifiable units + - **Atomic**: Can be completed in one commit or turn + - **Verifiable**: Has a concrete pass/fail check + +2. **Draft the Work Document**: + - Create file: `docs/work/-.md` + - Use the template below. + +3. **Execute Loop**: + - Pick an item + - Implement it + - Run the verification command + - Mark `[x]` only after verification passes + - Record evidence in the audit trail + +## The Template + +```markdown +# Work: [Title] + +## Intent +Link to: docs/intent/... + +## Approach +Link to: docs/approach/... + +## Checklist + +- [ ] **W001**: [Action] + - Verification: `[command to prove it works]` +- [ ] **W002**: [Action] + - Verification: `[command]` + +## Verification Evidence + +- [timestamp] W001: `[command]` → [result summary] +- [timestamp] W002: `[command]` → [result summary] + +## Notes + +Decisions, blockers, and learnings during execution. +``` + +## When the Plan Breaks + +Reality doesn't always match the Approach. Use this heuristic: + +**Note and continue** if: +- Implementation detail changes (different library, different API) +- Minor friction that doesn't affect architecture +- Add a note in the Work doc explaining the deviation + +**Stop and escalate to Approach** if: +- A core assumption is wrong +- The architecture needs to change +- The strategy won't achieve the Intent + +When escalating: +1. Document what broke and why in the Work doc +2. Update the Approach doc with the new strategy +3. Resume Work with revised plan + +## Validation + +Before starting a Ralph loop or handing off, validate the Work doc: + +**Required sections:** +- [ ] Intent link (reference to `docs/intent/...`) +- [ ] Approach link (reference to `docs/approach/...`) +- [ ] Checklist with `W001`, `W002`, etc. format +- [ ] Verification command for each checklist item +- [ ] Evidence section (can be empty at start) + +**Each checklist item must have:** +- [ ] Clear action description +- [ ] Verification command that produces pass/fail + +**Warnings:** +- Item marked `[x]` without corresponding evidence entry +- Verification command missing or vague ("check it works") +- Checklist item too large (should be atomic) + +Run validation by reviewing the doc against this checklist before starting work. + +## Rules + +- **Evidence Over Confidence**: Never say "I implemented X." Say "I implemented X and verified it with Y." +- **Small Batches**: If a work item takes more than ~10 minutes to verify, break it down. +- **Trace to Intent**: Does this work item actually serve the original intent?