synesenom/ran / .claude/skills/plan
plan
VerifiedPlan Command
You are creating a detailed implementation plan based on research findings.
Core Principle
Transform research into ACTIONABLE, PHASED implementation steps with clear success criteria.
Workflow
When the user invokes /plan <description>, /plan <research-file>, or /plan <github-issue>:
1. Resolve GitHub Issue (if applicable)
- If the query contains a GitHub issue URL or reference (e.g.
#123):- Fetch the issue details using:
gh issue view <number-or-url>(ormcp__github__issue_readifghis unavailable) - Use the issue title and body as planning context
- Check the current branch and create a development branch if needed (same logic as
/research)
- Fetch the issue details using:
2. Gather Context
- Spawn the discovery-thoughts agent to find relevant prior work and past solutions
- If user references a research file, read it completely
- If past solutions are found, incorporate their prevention strategies into the plan
- If no research exists, spawn discovery-code and discovery-analyze agents to gather context
- Understand the goal and constraints
3. Auto-Resolve Design Decisions
Use a propose-critique agent loop to auto-resolve most decisions:
a. Spawn design agents:
- Spawn the design-propose agent with the decision description and context
- Wait for proposals, then spawn the design-critique agent with the proposals and original context
b. Synthesize the result:
- If both agents agree and confidence is High: Auto-select the recommended option. Inform the user but do not wait for confirmation.
- If confidence is Low or agents disagree: Escalate to the human with the options and the specific tradeoff.
c. Report the outcome:
For auto-resolved decisions:
"Design Decision (auto-resolved, high confidence):
Chose — <1 sentence reason>. Critique confirmed: follows existing patterns, low testing burden.
(Proceeding to plan structure.)"
For escalated decisions:
"Design Decision (needs your input):
Option 1: — Option 2: —
Tradeoff:
Which approach do you prefer?"
Then wait for user input before proceeding.
4. Write ADRs for Design Decisions
Write an ADR only when the decision affects the Distribution base class public API, the module export structure, cross-cutting conventions, or introduces/removes a dependency. Do not write an ADR for implementation-technique choices within a single distribution (which algorithm to use, which special function to call, formula variants).
For each decision that clears the bar:
a. Determine the next ADR number: List files in decisions/ and pick the next sequential number.
b. Write the ADR at decisions/NNNN-<slug>.md:
# ADR-NNNN: <Decision Title>
**Date**: YYYY-MM-DD
**Status**: Accepted
## Context
<What motivated this decision>
## Decision
<What was chosen and why>
## Consequences
<What becomes easier or harder>
c. Link the ADR at the most relevant code location as a WHY comment:
// See decisions/NNNN-slug.md
5. Propose Plan Structure
"Here's my proposed plan structure:
Overview
<1-2 sentence summary>
Implementation Phases:
- -
- - ..."
Proceed directly to creating the plan without waiting for confirmation.
6. Create Implementation Plan
Create the plan at:
thoughts/plans/YYYY-MM-DD-HHmm-<description-slug>.md
Use this format:
---
date: <ISO timestamp>
description: "<plan description>"
status: approved
related_research: "thoughts/research/YYYY-MM-DD-HHmm-<topic>.md"
---
# Implementation Plan: <description>
## Overview
<2-3 paragraph summary of what will be implemented and why>
## Design Decisions
- [ADR-NNNN: <title>](../../decisions/NNNN-slug.md) — <one-line summary>
<If no design decisions:>
No design decisions — straightforward implementation.
## Implementation Phases
### Phase 1: <Descriptive Name>
**Goal**: <What this phase accomplishes>
**Files to Modify**:
- `src/dist/<name>.js` — <What changes>
- `test/dist-cases.js` — <What test cases are added>
**Steps**:
1. [ ] <Specific action>
2. [ ] <Specific action>
**Success Criteria**:
- [ ] <Testable criterion>
**Verification**:
```bash
npm run standard
npm test
Phase 2:
Testing Strategy
- New distributions: add entry to
test/dist-cases.jswithinvalidParams,params, andcases - Statistical correctness: verify PDF integrates to 1, CDF is monotone, quantile inverts CDF
- Edge cases: parameter boundaries, support boundaries, extreme inputs
- Verify:
npm test
Learnings from Past Solutions
Risk Assessment
- High Risk:
- Medium Risk:
- Low Risk:
Estimated Complexity
- Lines of Code: ~
- Files Modified: ~
### 7. Present to User
> "I've created the implementation plan at:
>
> `thoughts/plans/YYYY-MM-DD-HHmm-<description>.md`
>
> The plan includes:
> - <Phase 1 summary>
> - <Phase 2 summary>
>
> Once ready, start implementation with:
> `/implement thoughts/plans/YYYY-MM-DD-HHmm-<description>.md`"
## Rules
### DO:
- Use design-propose + design-critique agents for design decisions
- Auto-resolve high-confidence decisions; escalate low-confidence ones
- Break into logical, independently testable phases
- Call out exact files and what changes
- Make success criteria objective and verifiable
### DO NOT:
- Stop and ask the human about every design choice — use the agents first
- Create phases that can't be tested independently
- Treat plans as suggestions — they are specifications
- Include phases or steps that don't map to an acceptance criterion
- Propose adapting a statistical formula to use substitute inputs without first adding the required metric — statistical formulas have specific mathematical requirements that can't be silently substituted
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: 196k | 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: 193k | 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: 193k | 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: 193k | Updated | Claude CodeCodex | Verified | Install |