dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
skills/docs/intent-approach-work.md

7.5 KiB
Raw Blame History

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.

## 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.

## 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.

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

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

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

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