# My Plan > Draft a design/implementation plan for a change, pressure-test it with /dual-review (design mode), iterate with the user, then commit it under plans/. Use when the user wants to plan something before building it - "plan X", "let's plan the Y refactor", "/my-plan", "work up a plan for Z and review it". This is the planning dance for this repo - it produces a tracked plan doc, not code. - Skill: `idank/my-plan` (Agent Skill) - Install (CLI): `npx skillmds@latest add idank/my-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/idank/my-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: idank (https://skillmd.com/u/idank) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/idank/my-plan --- # My Plan Codifies this repo's planning workflow: **ground -> draft -> dual-review -> iterate -> commit**. The output is a reviewed plan document under `plans/`. It does **not** write production code - that's a later, separate build pass against the committed plan. This is tuned for `~/dev/vibe/explainshell`. Honor the repo conventions throughout: conventional-commit messages (`feat(web):`, `chore(deps):`, ...), commits go to `master`, and `CLAUDE.md`/`AGENTS.md` are the source of truth for structure, workflow, and settled conventions. ## Process 1. **Scope it.** Confirm what the plan is for. If the ask is vague, ask one or two sharp questions before drafting - a plan for the wrong thing wastes the review. 2. **Ground the plan in real code first.** This is the step that makes the plan worth reviewing. Read the actual files, symbols, routes, and schemas the change touches - do not hand-wave. Reference real `file:line`, function names, CLI subcommands, and DB tables. Check `CLAUDE.md`/`AGENTS.md` before reopening a settled convention or workflow call. A grounded plan names the crux (the hard tradeoff), the invariants it must preserve, and the open questions; a vague one does not. 3. **Write the plan to `plans/.md`.** Short kebab-case slug (e.g. `batch-extraction.md`). Structure that has worked: - A status line (`design draft - not yet implemented`) and the origin of the ask. - **Problem** - what's wrong today, grounded in real symbols. - **The crux** - the central tradeoff and the proposed resolution, with the alternative named. - **Changes** - extraction pipeline / matching / storage / web / tooling, concrete (function signatures, CLI flags, schema changes, routes). - **Invariants to preserve** - the conventions and design rules the change must not break. - **Tests and validation** - which suite applies (`make tests-quick` vs `make tests-all`), and whether the change needs an eval pass (`/eval-llm` for extractor changes, `/eval-render` for mandoc rendering changes) before it can land. - **Migration/data** - DB rebuild or `db-latest` release implications, if any. - **Open questions** - the calls you want the user (and the reviewers) to weigh. `plans/` is tracked in this repo (not gitignored) - the committed plan is the durable record. 4. **Dual-review it.** Invoke the `dual-review` skill in **design** mode pointed at the plan: `/dual-review design plans/.md`. Let it run both reviewers (codex + a Claude subagent) and produce the synthesis. Do not skip this - the cross-check is the point of the dance. 5. **Synthesize and iterate with the user.** Present the synthesis: where the reviewers agree (highest confidence), what each caught that the other missed, and - critically - **push back where a reviewer contradicts the repo's own docs** (`CLAUDE.md`/`AGENTS.md`, an invariant, an established workflow), with the citation. Then propose a revision set (apply / defer / skip-with-reason). **Get the user's sign-off on the direction before editing the plan** - this is a human-in-the-loop step, not an auto-apply. 6. **Fold accepted revisions into the plan body.** Update `plans/.md`: rewrite the affected sections, resolve the open questions with the review outcome, and record any findings deliberately **deferred** (e.g. spun out as follow-up work) so they aren't silently dropped. Note the review in the status line (`dual-reviewed (codex + claude ), revisions folded in`). 7. **Commit on sign-off.** When the user is satisfied, commit the plan with a conventional-commit message (e.g. `docs(plans): add design plan`). Commit to `master` per repo convention, but **don't push** unless asked - pushes to `master` trigger a production deploy via CI. Stage only the plan file - never bundle unrelated working-tree changes, and never commit production code from this skill. End your turn by reporting the commit hash. ## Constraints - **Plan, don't build.** This skill produces a plan document. It does not edit production code, run builds, or apply the change. The build is a separate pass against the committed plan. The `make format`/test workflow in `CLAUDE.md` doesn't apply here - the only output is markdown. - **Don't auto-apply review findings.** Synthesize, recommend, get sign-off, then fold in. The user decides what's adopted, deferred, or skipped. - **Don't commit without the user's go-ahead** on the plan's content. "Commit it" / clear satisfaction is the signal. - **Respect repo conventions:** check `CLAUDE.md`/`AGENTS.md` before reopening settled questions; plans that touch the LLM extractor or mandoc rendering must name the eval that will validate them. - If the user explicitly wants only some steps (e.g. "just draft it, skip the review"), follow that - the dance is the default, not a straitjacket.