Store Plan

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

Instructions
Output Path
Document Structure
Formatting Rules
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-store-plan 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 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:

mkdir -p plans/

Write to the path defined in 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

# {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 .

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:

## 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
: Use on the top-level # heading only

Example Output

# 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-based cache invalidation | P0 |
| 🟡 | Phase 2 | `server/core/qc_engine.py` | Background refresh on migration save | P1 |

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

## Action Items

**P0 — Do first:**
- [ ] Add `_compute_fingerprint()` to `server/core/qc_engine.py`
- [ ] Replace TTL check with fingerprint comparison in `run_qc_analysis()`
- [ ] Update tests in `server/tests/test_qc_cache.py`

**P1 — Do next:**
- [ ] Add background pre-warm after migration save in `server/core/migration_crud.py`

## Phase 1: Fingerprint-based invalidation

_Replace TTL caching with content-hash invalidation so QC results always reflect current data._

**Goal:** QC results invalidate immediately when migrations or source data change

**Steps:**
- [ ] Compute SHA-256 of migration JSON + source data file mtimes
- [ ] Store fingerprint alongside cached QC results
- [ ] Compare fingerprint on cache read; miss if different

**Verify:** `cd server && uv run pytest tests/test_qc_cache.py -v`

**Key files:**

| File | Change |
|------|--------|
| `server/core/qc_engine.py` | Add fingerprint logic, replace TTL check |
| `server/tests/test_qc_cache.py` | Add fingerprint invalidation tests |

## Phase 2: Background refresh

_Pre-warm QC cache after migration saves so the QC tab loads instantly._

**Goal:** QC tab shows fresh results without a loading spinner after migration edits

**Steps:**
- [ ] Fire async QC job after successful migration save
- [ ] Reuse existing `qc-start` job infrastructure

**Verify:** Save a migration, switch to QC tab — results should appear without "Running QC..."

## Risks & Open Questions

| S | Item | Impact | Notes |
|---|------|--------|-------|
| 🟡 | Large datasets may slow fingerprint computation | QC tab load time | Benchmark with biggest dataset first |
| 🟡 | Should fingerprint include excluded_files.json? | Correctness | Probably yes — decide during implementation |

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

cmd-store-plan