Kartik-Doye/Ravengard-AI-Recruiter / .agents/skills/masterplan
masterplan
VerifiedBuilds an implementation sequence from repository evidence using dependencies, invariants, vertical slices, rollback points, parallel work, irreversible decisions, and conscious deferrals. Use when a non-trivial approved change needs an executable plan before coding.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.6 KB |
| references/plan-template.md | markdown | 3.8 KB |
| references/planning-protocol.md | markdown | 1.5 KB |
| references/research.md | markdown | 794 B |
references/plan-template.md
View on GitHub# Plan template + worked example + anti-patterns
## Template
```markdown
<!-- generated by masterplan on YYYY-MM-DD -->
# Plan: <title>
**Brief:** docs/briefs/<slug>.md (or one-line goal)
**Verified against repo on:** YYYY-MM-DD @ <commit/branch>
## Current state → Target state
<2–6 lines each. Concrete, path-anchored.>
## Decisions
| # | Decision | Alternatives | Why | Wrong when |
| --- | --- | --- | --- | --- |
## Slices
### Slice 1: <name> (depends on:, )
- Action: <verb-led specific instructions, e.g., 'Create file at...', 'Add endpoint...'>
- Files: <real paths, verified>
- Validation Criteria: <measurable output for verification, e.g., 'unit tests pass', 'JSON response matches schema'>
- Rollback: <how to undo>
### Slice 2: <name> (depends on: 1) …
(Parallelizable: 3 ∥ 4: conflict: both touch <file>)
## Rollout & checkpoints
<Deploy/merge order; where the user reviews before continuing.>
## Risks
| Risk | Likelihood | Mitigation |
## Definition of done
- [ ] <acceptance criterion>: proven by <command/check>
```
## Worked example (abridged)
Brief: dark mode toggle (see distill's worked example).
```markdown
## Current state
Tailwind + CSS variables (`tailwind.config.ts`), no theme persistence,
no preference storage.
## Target state
`dark` class on <html>, toggled from header + settings, persisted in
localStorage, OS-preference default, no first-paint flash.
## Decisions
| # | Decision | Alternatives | Why | Wrong when |
| - | --- | --- | --- | --- |
| 1 | class strategy (`dark:` variant) | media-query strategy | needs manual toggle | we drop manual toggle |
| 2 | localStorage, no server storage | user table column | no auth exists yet | per-user sync lands |
## Slices
### Slice 1: theme foundation (depends on:, )
- Action: Wire CSS variables for both palettes and establish `dark` class strategy.
- Files: `tailwind.config.ts`, `src/styles/theme.css`
- Validation Criteria: Manual class flip on <html> in devtools correctly flips color palettes.
- Rollback: revert commit
### Slice 2: toggle + persistence (depends on: 1)
- Action: Build header toggle component, wire localStorage persistence, and set OS default fallback.
- Files: `src/components/ThemeToggle.tsx` (new), `src/app/layout.tsx`, `src/components/Header.tsx`
- Validation Criteria: Unit tests for preference read/write pass. UI toggle persists across page reload.
- Rollback: revert commit (no data migration involved)
### Slice 3: flash-free first paint (depends on: 2)
- Action: Inject inline pre-hydration script into document head to set class before body paint.
- Files: `src/app/layout.tsx`
- Validation Criteria: e2e test confirms no light-mode flash on hard reload when dark preference is set.
- Rollback: revert commit
## Risks
| Risk | Likelihood | Mitigation |
| --- | --- | --- |
| Third-party components ignore variables | medium | audit in slice 1, fallback CSS |
## Definition of done
- [ ] Toggle persists across reload: proven by unit + manual check
- [ ] No wrong-theme flash: proven by e2e in slice 3
- [ ] `npm run build` && `npm test` green
```
Three slices, each independently verifiable. Note there is no "step 9:
add useState" nonsense.
## Anti-patterns
1. **The 70-microstep plan**: "create folder / create file / add import /
run build" × 20. Means slicing failed; merge into real slices.
2. **Speculative paths**: `src/utils/helpers.ts` that was never opened.
Plan says "confirm location in slice N" instead.
3. **Horizontal slicing**: "slice 1: all the API, slice 2: all the UI"
→ nothing is verifiable until the end. Cut vertically.
4. **Rollback = "trust me"**: every destructive step names its undo.
5. **The plan that restates the brief**: reference it, don't copy it.
6. **Decision-free plans**: every "should we X or Y" left open means the
implementer (a weaker model, maybe) decides by accident later.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |