# Goal Decomposition

## Description
Best practices for decomposing complex goals into executable checkpoints.

## Triggers
- goal
- plan
- long-term
- multi-step
- project
- achieve
- milestone

## Instructions

### Decomposition Principles
1. **Concrete over abstract** — Each checkpoint should produce a tangible artifact
   or verifiable outcome, not "think about X"
2. **3-10 checkpoints** — Too few = checkpoints too complex. Too many = overhead.
3. **Research before action** — First checkpoint should always gather information
4. **Verify before proceeding** — Include verification steps as success_criteria,
   not as separate checkpoints
5. **Front-load unknowns** — Put uncertain/risky checkpoints early so failure is cheap

### Success Criteria Rules
- Must be **objectively verifiable** — "file exists at path X", "3 positions found",
  "test passes"
- No subjective criteria — avoid "good quality", "well-written"
- Include quantities when possible — "at least 3", "under 500 words"

### When to Revise
- New information invalidates assumptions (company isn't hiring)
- A checkpoint reveals the plan is missing steps
- User provides feedback that changes direction
- 2+ checkpoint failures suggest wrong approach

### Anti-patterns
- Don't create a goal for tasks completable in <5 tool calls
- Don't make checkpoints that depend on external timing ("wait for response")
  — instead pause the goal and set a scheduled reminder to resume
- Don't put all complexity in one checkpoint — if a checkpoint needs 50+ tool
  calls, it should be split

## Examples

### Good Decomposition: Job Application
Goal: "Get a job at company X"
1. Research X (culture, stack, recent news) — criteria: summary written
2. Find open positions — criteria: 3+ positions listed with URLs
3. Tailor resume — criteria: resume file updated, relevant skills highlighted
4. Draft cover letter — criteria: cover letter file created, <400 words
5. Submit application — criteria: confirmation page screenshot saved

### Good Decomposition: Portfolio Website
Goal: "Build me a portfolio website"
1. Research design trends and gather requirements — criteria: design brief written
2. Set up project (Next.js + deployment target) — criteria: project scaffolded, dev server runs
3. Build core pages (home, about, projects) — criteria: 3 pages render with placeholder content
4. Add real content and styling — criteria: all sections populated, responsive on mobile
5. Deploy to production — criteria: live URL accessible, no console errors

### Good Decomposition: Security Audit
Goal: "Audit this codebase for security vulnerabilities"
1. Scan dependencies for known CVEs — criteria: dependency report generated
2. Review authentication and session handling — criteria: auth flow documented, issues listed
3. Check for injection vulnerabilities (SQL, XSS, command) — criteria: each input path tested
4. Write audit report with severity ratings — criteria: report file created, findings prioritized

### Bad Decomposition
Goal: "Get a job at company X"
1. Do research (too vague, no criteria)
2. Apply (too broad, should be multiple steps)
3. Wait for response (depends on external timing)

## Verify

- The deliverable for this phase exists as a concrete artifact (doc, ticket, board, repo) and its location is shared, not described
- Each commitment has an owner name, a due date, and a definition-of-done that someone other than the author could check
- Risks are listed with likelihood/impact and a named mitigation, not as a generic 'risks: TBD' bullet
- Dependencies on other teams/vendors/agents are explicit; an ack from each dependency is recorded or marked 'pending'
- Success criteria for the next phase are numeric or otherwise objectively testable
- A rollback / kill-switch / 'we will stop if X' criterion is written down before work starts

## Notes
- Always check if a goals/SKILL.md is relevant before creating a goal
- The goal system handles persistence, context, and auto-continuation automatically
- Use goal_status to check progress at any time
