dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: Intent/Approach/Work planning framework

Browse source
This commit is contained in:
dan 2026-01-18 20:20:51 -08:00
parent 057f89660f
commit 8dc4a6c9df
1 changed files with 292 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

292
docs/intent-approach-work.md Normal file
View file

@ -0,0 +1,292 @@
# Intent / Approach / Work
A lightweight planning framework for AI-assisted coding.
## Why Structure?
AI coding assistants work best with explicit phases and human checkpoints. Without structure:
- AI hallucinates solutions before understanding the problem
- Context drifts mid-implementation
- Complexity gets papered over instead of surfaced
This framework forces **Chain of Thought** into the workflow: separate *what* from *how* from *do*.
## The Four Phases
```
Intent → [approve] → Approach → [approve] → Work → [execute] → Review → [done]
```
Human gates at every transition. Don't rubber-stamp—add a critique or constraint to prove you read it.
### Intent (what)
| Field | Purpose |
|-------|---------|
| **Problem** | What's broken or missing? |
| **Context** | What code/docs were read to understand this? |
| **Edge cases** | What could go wrong? (AI is happy-path oriented) |
| **Solution** | High-level approach, not technical |
| **Constraints** | Requirements, limits, must-haves |
### Approach (how)
| Field | Purpose |
|-------|---------|
| **Technical** | How we'll solve it |
| **Interfaces** | Types/signatures before logic |
| **Rejected alternatives** | What we considered and why not |
| **Verification** | How we'll prove success (test command, manual check) |
| **Side effects** | Security, performance, auth implications |
| **Rollback** | How to undo if it fails |
| **Non-goals** | What we will NOT touch |
| **Files** | What we'll change |
### Work (do)
- **Pre-flight check**: "I have all info needed. Missing: [X]"
- Concrete steps as checkboxes
- First step often: write the failing test
- Commit after 1-2 checkboxes (atomic commits)
### Review (verify)
- [ ] Diff matches Intent
- [ ] Verification passed (paste raw output)
- [ ] Scaffolding removed (debug prints, commented code)
- [ ] Linter passes
- [ ] Docs updated if needed
---
## Templates
### Full Template
Use when: Rule of Three triggered, security/auth/data involved, or new feature.
```markdown
## Intent
**Problem**: What's broken or missing
**Context**: Code/docs read (include versions/hashes for long sessions)
**Edge cases**: What could go wrong?
**Solution**: High-level approach (not technical)
**Constraints**: Requirements, limits, must-haves
## Approach
**Technical**: How we'll solve it
**Interfaces**: Types/signatures we'll create or modify
**Rejected alternatives**: What we considered and why not
**Verification**: How we'll prove success (prefer: specific test command)
**Side effects**: Security, performance, auth implications
**Rollback**: How to undo if it fails
**Non-goals**: What we will NOT touch
**Files**:
- path/to/file.ts (change description)
## Work
**Pre-flight**: I have all info needed. Missing: [none]
- [ ] Write failing test for X
- [ ] Implement X
- [ ] Step 3
## Review
- [ ] Diff matches Intent
- [ ] Verification passed (paste output)
- [ ] Scaffolding removed
- [ ] Linter passes
- [ ] Docs updated
```
### Medium Template
Use when: 2-3 files, straightforward change, some edge cases.
```markdown
## Intent
**Problem**: What's broken
**Solution**: How we'll fix it
**Edge cases**: What could go wrong?
## Approach
**Technical**: How we'll solve it
**Verification**: How we'll prove success
**Files**:
- path/to/file.ts (change)
## Work
- [ ] Step 1
- [ ] Step 2
## Review
- [ ] Verification passed
- [ ] Cleanup done
```
### Minimal Template
Use when: Single file, obvious fix, low risk.
```markdown
## Intent
[One-liner: what and why]
## Work
- [ ] Step 1
- [ ] Step 2
```
---
## When to Use Structure
**Rule of Three** (+ security trigger):
- Affects >3 files
- Introduces >1 new dependency
- Changes existing interface/API
- Involves security, auth, or data persistence
If any true → use full structure. Otherwise, use judgment.
---
## Workflow Mechanics
### Human Gates
Don't just click approve. Add a critique, constraint, or question. If you can't find anything wrong, you didn't read it carefully enough.
### Context Anchoring
During Work phase, re-inject Intent + Approach summary. Don't rely on chat history alone—AI will drift by step 5.
### Pivot Protocol
When Work reveals Approach was wrong:
1. **Stop** - don't hack around it
2. **Diagnose** - summarize WHY it failed
3. **Learn** - add failure as negative constraint to Intent
4. **Revert** - return to Approach phase
5. **Revise** - update Approach with new constraint
Trigger pivot if changing >2 lines of Approach to make Work succeed.
### Complexity Promotion
When a Work item grows complex:
- Promote it to its own bead with full Intent/Approach/Work
- Original checkbox becomes reference to new bead
- Max depth: 2 levels of nesting
---
## Examples
### Full: Rate Limiting Feature
```markdown
## Intent
**Problem**: API has no rate limiting, vulnerable to abuse
**Context**: Read src/middleware/auth.ts, src/routes/api.ts
**Edge cases**: Redis unavailable, clock skew, boundary conditions
**Solution**: Add per-user rate limits using sliding window
**Constraints**: <5ms latency, graceful degradation
## Approach
**Technical**: Redis sorted sets for sliding window. Middleware on /api/*.
**Interfaces**:
interface RateLimitConfig { windowMs: number; maxRequests: number }
**Rejected alternatives**: In-memory (no multi-instance), fixed window (thundering herd)
**Verification**: npm test -- --grep "rate limit"
**Side effects**: Adds Redis dependency, clients need 429 handling
**Rollback**: Remove middleware, delete rateLimit.ts
**Non-goals**: Admin bypass, per-endpoint limits
**Files**:
- src/middleware/rateLimit.ts (new)
- src/routes/api.ts (add middleware)
- tests/rateLimit.test.ts (new)
## Work
**Pre-flight**: Have all info. Missing: none
- [ ] Write failing test for 429 response
- [ ] Implement sliding window counter
- [ ] Create middleware
- [ ] Wire to routes
- [ ] Add graceful degradation test
## Review
- [ ] 5/5 tests pass
- [ ] No debug prints
- [ ] README updated
```
### Medium: Timezone Bug Fix
```markdown
## Intent
**Problem**: Dates show "Invalid Date" for Asia/Tokyo users
**Solution**: Use UTC internally, format at display
**Edge cases**: DST transitions, pre-1970 dates
## Approach
**Technical**: Replace new Date(str) with dayjs.utc(str)
**Verification**: npm test -- --grep "formatDate" + manual TZ check
**Files**:
- src/utils/date.ts
- src/components/DateDisplay.tsx
## Work
- [ ] Add failing test with Tokyo fixture
- [ ] Fix date.ts
- [ ] Update DateDisplay
- [ ] Manual verify with TZ=Asia/Tokyo
## Review
- [ ] Tests pass
- [ ] Manual check done
```
### Minimal: Typo Fix
```markdown
## Intent
Fix "recieve" → "receive" in error message
## Work
- [ ] Update src/errors.ts:42
- [ ] Grep for other instances
```
---
## Meta-Insight
> "Intent compresses the Past, Approach compresses the Future, Work is the Decompression."
The critical success factor is **strictness of Human Gates**. Rigorous Approach review = magic Work phase. Rubber-stamp = hallucination engine.
---
## Prior Art
| Framework | Phase 1 | Phase 2 | Phase 3 | Phase 4 |
|-----------|---------|---------|---------|---------|
| GitHub Spec-Kit | Specify | Plan | Tasks | Implement |
| Amazon Kiro | Requirements | Design | Tasks | - |
| Traditional SDLC | Requirements | Design | Implementation | Testing |
| **This** | **Intent** | **Approach** | **Work** | **Review** |
## References
- [Martin Fowler: SDD Tools Comparison](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
- [GitHub Spec-Kit](https://github.com/github/spec-kit)
- [Amazon Kiro](https://kiro.dev/)
- [AGENTS.md Standard](https://agents.md)
- [Addy Osmani: LLM Coding Workflow](https://addyosmani.com/blog/ai-coding-workflow/)