feat(triad): rewrite Intent/Approach/Work skills
Intent: removed 'volition' terminology, reframed around motivation/need/use-cases, emphasize interrogation over inference Approach: cleaner strategy template, explicit trade-offs and risks Work: added validation checklist for doc structure, added 'When the Plan Breaks' escalation heuristic
This commit is contained in:
parent
f2d7fd7451
commit
89e150789c
26
skills/approach/README.md
Normal file
26
skills/approach/README.md
Normal file
|
|
@ -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/<date>-<slug>.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.
|
||||
70
skills/approach/SKILL.md
Normal file
70
skills/approach/SKILL.md
Normal file
|
|
@ -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/<date>-<slug>.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.
|
||||
36
skills/intent/README.md
Normal file
36
skills/intent/README.md
Normal file
|
|
@ -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/<date>-<slug>.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.
|
||||
68
skills/intent/SKILL.md
Normal file
68
skills/intent/SKILL.md
Normal file
|
|
@ -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/<date>-<slug>.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.
|
||||
26
skills/work/README.md
Normal file
26
skills/work/README.md
Normal file
|
|
@ -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.
|
||||
111
skills/work/SKILL.md
Normal file
111
skills/work/SKILL.md
Normal file
|
|
@ -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/<date>-<slug>.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?
|
||||
Loading…
Reference in a new issue