cmd-plan-store

What this skill does

# Store Plan <!-- omit in toc -->

Capture the current conversation into a structured, reviewable plan file.

- [Instructions](#instructions)
  - [1. Gather context](#1-gather-context)
  - [2. Generate the plan document](#2-generate-the-plan-document)
  - [3. Write and confirm](#3-write-and-confirm)
- [Output Path](#output-path)
- [Document Structure](#document-structure)
  - [Header Block](#header-block)
  - [tl;dr](#tldr)
  - [Context](#context)
  - [Decisions Made](#decisions-made)
  - [Plan Overview](#plan-overview)
  - [Action Items](#action-items)
  - [Phases / Sections](#phases--sections)
  - [Risks & Open Questions](#risks--open-questions)
  - [References](#references)
- [Formatting Rules](#formatting-rules)
  - [Status Circles](#status-circles)
  - [Tables](#tables)
  - [General](#general)
- [Example Output](#example-output)

## Instructions

### 1. Gather context

Scan the full conversation for:
- **Decisions** — what was agreed on and why
- **Action items** — concrete next steps with owners/priorities
- **Architecture or design choices** — trade-offs discussed
- **Risks and open questions** — unresolved items
- **Phases or ordering** — any sequencing that was discussed

If the user passed a description as an argument (e.g., `/cmd-plan-store auth refactor`), use it as `DESCRIPTION`. Otherwise, infer a 2-4 word slug from the conversation topic.

### 2. Generate the plan document

Build the document using the [Document Structure](#document-structure) below. Not every section is required — **omit sections that have no content** rather than leaving them empty. The goal is a document that someone (including future-you) can pick up cold and understand what was decided, what's next, and why.

Present the draft to the user before writing.

### 3. Write and confirm

**Step 3a — Write the file:**

```bash
mkdir -p plans/
```

Write to the path defined in [Output Path](#output-path).

**Step 3b — Confirm with the user:**

Present the file path and a brief summary to the user. Ask if they want to adjust anything before finalizing.

## Output Path

```
plans/{YYYY}_{MM}_{DD}_{description}.md
```

Examples:
- `plans/2026_04_02_auth_refactor.md`
- `plans/2026_04_02_frontend_split.md`
- `plans/2026_04_02_migration_engine_redesign.md`

## Document Structure

### Header Block

```markdown
# {Title} <!-- omit in toc -->

Date: YYYY-MM-DD
Source: conversation with Claude

- [Table of Contents entries...]
```

Always include a Table of Contents. Omit the top-level heading from the ToC using `<!-- omit in toc -->`.

### tl;dr

_Single italicized sentence (max 120 chars) summarizing the most important outcome or decision._

Place immediately after the ToC, before any sections.

### Context

Brief background on what prompted this plan. 2-4 bullets max. Include:
- What problem or goal kicked off the conversation
- Any constraints or deadlines mentioned
- Relevant prior work or plans referenced

### Decisions Made

A table summarizing key decisions from the conversation:

| S | Decision | Rationale |
|---|----------|-----------|
| 🟢 | What was decided | Why this choice was made |
| ... | ... | ... |

> 🟢 Approved · 🟡 Tentative · 🔴 Rejected · ⚪ Deferred

### Plan Overview

High-level summary table of phases or work items:

| S | Phase / Item | Component | Description | Priority |
|---|-------------|-----------|-------------|----------|
| 🟢 | Phase 1 | `module.py` | What this phase does | P0 |
| 🟡 | Phase 2 | `client/js/` | What this phase does | P1 |
| ⚪ | Future | TBD | Deferred work | P2 |

> 🟢 Ready to start · 🟡 Needs more detail · 🔴 Blocked · ⚪ Deferred

Priority labels: **P0** (do first), **P1** (do next), **P2** (backlog)

### Action Items

Checkboxed list grouped by priority. Each item should be concrete and actionable:

**P0 — Do first:**
- [ ] Action item with `file_path` reference if applicable
- [ ] Another action item

**P1 — Do next:**
- [ ] Action item
- [ ] Action item

**P2 — Backlog:**
- [ ] Action item

### Phases / Sections

For multi-phase plans, expand each phase with:

```markdown
## Phase N: {Name}

_One-line italicized summary of what this phase achieves._

**Goal:** What success looks like

**Steps:**
- [ ] Step 1 — description
- [ ] Step 2 — description

**Verify:** How to confirm this phase is done (e.g., `cd server && uv run pytest`)

**Key files:**

| File | Change |
|------|--------|
| `path/to/file.py` | What changes |
```

Only include phases that were actually discussed. Don't invent phases.

### Risks & Open Questions

| S | Item | Impact | Notes |
|---|------|--------|-------|
| 🔴 | Risk or blocker | What breaks if unaddressed | Mitigation or next step |
| 🟡 | Open question | What it affects | Who needs to answer |
| ⚪ | Nice-to-know | Low impact | Context for later |

> 🔴 High risk · 🟡 Medium / open question · ⚪ Low / informational

### References

Bullet list of links, prior plans, or external resources mentioned:
- `plans/prior_plan.md` — what it covers
- URL or resource — what it covers

## Formatting Rules

### Status Circles

Use colored circles consistently as the first column in all tables:

| Circle | Meaning (adapt label to section context) |
|--------|------------------------------------------|
| 🟢 | Positive: approved, ready, new, complete |
| 🟡 | Caution: tentative, needs detail, in progress |
| 🔴 | Negative: rejected, blocked, high risk, critical |
| ⚪ | Neutral: deferred, informational, no action |

Always include a one-line legend as a blockquote below each table explaining what the circles mean in that context.

### Tables

- Use tables for structured comparisons, decision logs, and overviews
- Keep cells concise — short phrases, not paragraphs
- Use backticks for all code references in table cells
- Include a **Priority** column when items have different urgency
- Include a **Rationale** or **Notes** column when context matters

### General

- **Checkboxes** (`- [ ]`): Use for all actionable items so the user can track progress
- **Italicized tl;drs**: Every major section can optionally have a one-line italic summary
- **Headings**: Use `##` for major sections, `###` for subsections. Don't go deeper than `####`
- **Code references**: Always use backticks for file names, paths, commands, functions, config keys
- **Bullet points over paragraphs**: Break any explanation longer than 2 sentences into bullets
- **No filler**: Skip "this section covers..." preambles. Lead with the content
- **`<!-- omit in toc -->`**: Use on the top-level `#` heading only

## Example Output

```markdown
# QC Cache Redesign <!-- omit in toc -->

Date: 2026-04-02
Source: conversation with Claude

- [tl;dr](#tldr)
- [Context](#context)
- [Decisions Made](#decisions-made)
- [Plan Overview](#plan-overview)
- [Action Items](#action-items)
- [Phase 1: Fingerprint-based invalidation](#phase-1-fingerprint-based-invalidation)
- [Phase 2: Background refresh](#phase-2-background-refresh)
- [Risks & Open Questions](#risks--open-questions)

_tl;dr Replace time-based QC cache with fingerprint-based invalidation to eliminate stale results after migrations._

## Context

- QC results were cached with a 5-minute TTL, causing stale data after migration edits
- Users reported QC tab showing pre-migration outliers after applying fixes
- Prior plan: `plans/2026_03_28_staleness_system.md`

## Decisions Made

| S | Decision | Rationale |
|---|----------|-----------|
| 🟢 | Use content fingerprint, not timestamps | Timestamps miss in-place edits to migration JSON |
| 🟢 | Hash migration file + source data | Captures both data changes and rule changes |
| 🟡 | Consider background pre-warming | Deferred — evaluate after P0 lands |
| 🔴 | Rejected: per-field granular caching | Too complex for current data volume |

> 🟢 Approved · 🟡 Tentative · 🔴 Rejected · ⚪ Deferred

## Plan Overview

| S | Phase | Component | Description | Priority |
|---|-------|-----------|-------------|----------|
| 🟢 | Phase 1 | `server/core/qc_engine.py` | Fingerprint-b