plan-documentation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Plan Documentation

Generate structured plan files when starting large features, refactoring efforts, or multi-phase work. Plans create a paper trail that survives context resets and helps collaborators understand what was planned, what changed, and why.

## When to Generate Plan Files

Create a plan document when:
- The task spans more than 2 files or requires multiple coordinated changes
- Work will take more than one session or phase
- Multiple approaches exist and the chosen path should be documented
- Other people (or future you) need to understand the sequence of work

Do NOT create plan files for:
- Single-file fixes or tweaks
- Routine maintenance (dependency updates, formatting)
- Tasks that can be completed in under 15 minutes

## Plan Document Template

Create the plan at `plans/<task-slug>-plan.md` in the project root.

```markdown
# Plan: <Task Title>

Created: <ISO date>
Status: IN_PROGRESS | COMPLETE | ABANDONED

## Summary

<2-3 sentences explaining what this work accomplishes and why it matters.>

## Phases

### Phase 1: <Phase Title>
- [ ] Step 1 description
- [ ] Step 2 description
- [ ] Step 3 description

**Acceptance Criteria:**
- <What must be true when this phase is done>
- <Measurable or verifiable condition>

### Phase 2: <Phase Title>
- [ ] Step 1 description
- [ ] Step 2 description

**Acceptance Criteria:**
- <Condition>

### Phase N: <Phase Title>
...

## Open Questions

1. <Question about approach or requirement> -- Suggested: <Option A> vs <Option B>
2. <Question about scope> -- Suggested: <Option A> vs <Option B>
3. <Question about dependency or risk> -- Suggested: <Option A>

Keep open questions between 1-5. Each should have suggested options so they can be resolved quickly. Remove questions as they get answered -- move the decision to the relevant phase.

## Dependencies

- <External system, API, library, or team dependency>
- <Prerequisite work that must finish first>

## Risks

- <What could go wrong and how likely it is>
- <Mitigation strategy if applicable>
```

## Phase Completion Template

After finishing each phase, create `plans/<task-slug>-phase-N-complete.md`:

```markdown
# Phase N Complete: <Phase Title>

Completed: <ISO date>
Plan: <task-slug>-plan.md

## Phase N Summary

<1-2 sentences on what was accomplished.>

## What Changed

| File | Change |
|------|--------|
| `path/to/file.ts` | Added validation logic for user input |
| `path/to/test.ts` | 6 new unit tests for validation edge cases |

## What Was Tested

- <Test suite or manual verification performed>
- <Edge cases covered>
- <What was NOT tested and why>

## Decisions Made

- <Decision>: <Why this option was chosen over alternatives>

## Next Phase Preview

Phase N+1 will focus on <brief description>. Prerequisites met: <yes/no>.
```

## Final Completion Template

When all phases are done, create `plans/<task-slug>-complete.md`:

```markdown
# Complete: <Task Title>

Completed: <ISO date>
Plan: <task-slug>-plan.md
Duration: <how long the work took>

## Task Summary

From vibeeval/vibecosystem, MIT.

More from vibeeval/vibecosystem