plannotator-compound

What this skill does

# Compound Planning Analysis

You are conducting a comprehensive research analysis of a user's Plannotator plan
archive. The goal: extract patterns from their denied plans, reduce
them into actionable insights, and produce an elegant HTML dashboard report.

This is a multi-phase process. Each phase must complete fully before the next begins.
Research integrity is paramount — every file must be read, no skipping.

## Source Selection

Before starting the analysis, determine which data source is available.

1. **Plannotator mode (first-class)** — Determine the Plannotator data directory:
   use `$PLANNOTATOR_DATA_DIR` if set, otherwise `~/.plannotator`. Check the
   `plans/` subdirectory there. If it exists and contains `*-denied.md` files,
   use this mode. The entire workflow below is written for Plannotator data.

2. **Claude Code fallback mode** — If the Plannotator archive is absent or
   contains no denied plans, check `~/.claude/projects/`. If present, read
   [references/claude-code-fallback.md](references/claude-code-fallback.md)
   before continuing. That reference explains how to use the bundled parser at
   [scripts/extract_exit_plan_mode_outcomes.py](scripts/extract_exit_plan_mode_outcomes.py)
   to extract denial reasons from Claude Code JSONL transcripts. Every phase
   below has a short note explaining what changes in fallback mode — the
   reference file has the details.

3. **Neither available** — Ask the user for their Plannotator plans directory or
   Claude Code projects directory. Do not guess.

## Phase 0: Locate Plans & Check for Previous Reports

Use the mode chosen in Source Selection above.

**Plannotator mode:** Verify the plans directory contains `*-denied.md` files. If
none exist, fall back to Claude Code mode before stopping.

**Claude Code fallback mode:** Run the bundled parser per the fallback reference to
build the denial-reason dataset. Create `/tmp/compound-planning/` if needed.

In either mode, proceed to Previous Report Detection below.

### Previous Report Detection

After locating the plans directory, check for existing reports:

```
ls ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/compound-planning-report*.html
```

Reports follow a versioned naming scheme:
- First report: `compound-planning-report.html`
- Subsequent reports: `compound-planning-report-v2.html`, `compound-planning-report-v3.html`, etc.

If one or more reports exist, determine the **latest** one (highest version number).
Get its filesystem modification date using `stat` (macOS: `stat -f %Sm -t %Y-%m-%d`,
Linux: `stat -c %y | cut -d' ' -f1`). This is the **cutoff date**.

Present the user with a choice:

> "I found a previous report (`compound-planning-report-v{N}.html`) last updated
> on {CUTOFF_DATE}. I can either:
>
> 1. **Incremental** — Only analyze files dated after {CUTOFF_DATE}, saving tokens
>    and building on previous findings
> 2. **Full** — Re-analyze the entire archive from scratch
>
> Which would you prefer?"

Wait for the user's response before proceeding.

**If incremental:** Filter all subsequent phases to only process files with dates
after the cutoff date. The new report version will note in its header narrative that
it covers the period from {CUTOFF_DATE} to present, and reference the previous
report for earlier findings. The inventory (Phase 1) should still count ALL files
for overall stats, but clearly separate "new since last report" counts.

**If full:** Proceed normally with all files, but still use the next version number
for the output filename.

**If no previous report exists:** Proceed normally. The output filename will be
`compound-planning-report.html` (no version suffix for the first report).

## Phase 1: Inventory

Count and report the dataset. **Always count ALL files** for overall stats,
regardless of whether this is an incremental or full run:

```
- *-approved.md files (count)
- *-denied.md files (count)
- Date range (earliest to latest date found in filenames)
- Total days spanned
- Revision rate: denied / (approved + denied) — this is the "X% of plans
  revised before coding" stat used in dashboard section 1
```

**Note:** Ignore `*.annotations.md` files entirely. Denied files already contain
the full plan text plus all reviewer feedback appended after a `---` separator.
Annotation files are redundant subsets of this content — reading both would
double-count feedback.

**If incremental mode:** After the total counts, separately report the counts for
files dated after the cutoff date only:

```
New since {CUTOFF_DATE}:
- *-denied.md files: X (of Y total)
- New date range: {CUTOFF_DATE} to {LATEST_DATE}
- New days spanned: N
```

If fewer than 3 new denied files exist since the cutoff, warn the user:
> "Only {N} new denied plans since the last report. The incremental analysis may
> be thin. Would you like to proceed or switch to a full analysis?"

Also run `wc -l` across all `*-approved.md` files to get average lines per
approved plan. This tells the user whether their plans are staying lightweight
or bloating over time. You do not need to read approved plan contents — just
their line counts. If possible, break this down by time period (e.g., monthly)
to show whether plan size changed.

Dates appear in filenames in YYYY-MM-DD format, sometimes as a prefix
(2026-01-07-name-approved.md) and sometimes embedded (name-2026-03-15-approved.md).
Extract dates from all filenames.

Tell the user what you found and that you're beginning the extraction.

**Claude Code fallback mode:** The Plannotator inventory fields above do not apply.
Follow the inventory instructions in
[references/claude-code-fallback.md](references/claude-code-fallback.md) instead —
report the denial-reason dataset assembled by the parser.

## Phase 2: Map — Parallel Extraction

This is the most time-intensive phase. You must read EVERY `*-denied.md` file
**in scope**. Do not skip files. Do not summarize early.

**In scope** means: all denied files if running a full analysis, or only denied
files dated after the cutoff date if running incrementally. In incremental mode,
only process files whose embedded YYYY-MM-DD date is strictly after the cutoff.

**Claude Code fallback mode:** The parser output is the clean source dataset. Read
the fallback reference for the extraction prompt and batching strategy specific to
JSON part files. Do not go back to raw `.jsonl` logs unless the parser fails or the
user asks for audit-level verification.

**Important:** Only read `*-denied.md` files. Do NOT read approved plans,
annotation files, or diff files. Each denied file contains the full plan text
followed by a `---` separator and the reviewer's feedback — everything needed
for analysis is in one file.

### Batching Strategy

All extraction agents should use `model: "haiku"` — they're doing straightforward
file reading and structured extraction, not reasoning. Haiku is faster and cheaper
for this work.

The approach depends on dataset size:

**Tiny datasets (≤ 10 total files):** Read all files directly in the main agent —
no need for sub-agents. Just read them sequentially and proceed to Phase 3.

**Small datasets (11-30 files):** Launch 2-3 parallel Haiku agents, splitting
files roughly evenly.

**Medium datasets (31-80 files):** Launch 4-6 parallel Haiku agents (~10-15 files
each). Split by file type and/or time period.

**Large datasets (80+ files):** Launch as many parallel Haiku agents as needed to
keep each batch around 10-15 files. Split by the natural time boundaries in the
data (months, quarters, or whatever groupings produce balanced batches). If one
time period dominates (e.g., the most recent month has 3x the files), split that
period into multiple batches.

Launch all extraction agents in parallel using the Agent tool with
`run_in_background: true` and `model: "haiku"`.

### Output Files

Each extraction agent must write its results to a clean output file rather than
relying on the agent task output (which contains interleaved JSONL framework
logs