skills/docs/intent-approach-work.md

# 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/)