timsimpsonjr/prose-craft/learn

Copydesk Learn

This skill manages the learning loop for copydesk. It captures snapshots of generated text at key pipeline stages, then (when invoked directly) dispatches the learn-review agent to analyze what the user changed by hand and propose improvements to the system.

This skill is independently invocable. It does not require copydesk to be active in the current session. It reads all files from disk.

Argument Detection

Check the invocation arguments to determine which mode to run.

• snapshot post-review, snapshot post-fixes, or snapshot suppression --> Mode 1: Snapshot Save
• evaluators --> Mode 3: Evaluator Correction
• A file path argument (e.g., /copydesk:learn path/to/edited-file.md) --> Mode 2: Learning Analysis, using that file
• No arguments (just /copydesk:learn) --> Mode 2: Learning Analysis, using the most recent snapshot set

Mode 1: Snapshot Save

Invoked by the copydesk skill during the review gate workflow. Does not interact with the user.

snapshot post-review

1. Create the directory ~/.claude/data/copydesk/learning/snapshots/ if it doesn't exist.

1. Derive a piece filename from the output file being written. Strip the extension and any path components. For example, /home/user/blog/my-post.md becomes my-post.

1. Generate a timestamp: YYYY-MM-DD-HHmm (24-hour, local time).

1. Write the CURRENT generated text (the text after review agents ran and hard fails were fixed, before the user sees advisories) to:

~/.claude/data/copydesk/learning/snapshots/{piece-filename}-{timestamp}-post-review.md

1. Write the generation brief to:

~/.claude/data/copydesk/learning/snapshots/{piece-filename}-{timestamp}-brief.md

The brief is everything that drove generation: the user's request, the source material (transcripts, research notes, outline), and any design-doc/brief used. This is what lets a piece be regenerated later for the held-out gate, so capture it verbatim rather than summarizing. If generation used a design doc on disk, record its path here too.

1. Write the review agent findings (both the prose review findings and the craft review advisory table) to:

~/.claude/data/copydesk/learning/snapshots/{piece-filename}-{timestamp}-review-findings.md

1. Update or create ~/.claude/data/copydesk/learning/snapshots/manifest.json. If the file exists, read it first and append to the snapshots array. If it doesn't exist, create it with a new array.

Entry format: ``json { "piece": "my-post", "timestamp": "2026-04-10-1430", "register": "personal", "brief": "my-post-2026-04-10-1430-brief.md", "postReview": "my-post-2026-04-10-1430-post-review.md", "reviewFindings": "my-post-2026-04-10-1430-review-findings.md" } ``

The register field comes from whichever register was active during generation.

snapshot post-fixes

1. Write the current text (after the user accepted/rejected/modified all advisory rows) to:

~/.claude/data/copydesk/learning/snapshots/{piece-filename}-{timestamp}-post-fixes.md

Use the same piece filename and timestamp as the matching post-review entry. Find the match by looking for the most recent manifest entry whose piece field matches the current output file.

1. Update the matching manifest entry to add the postFixes field:

``json { "piece": "my-post", "timestamp": "2026-04-10-1430", "register": "personal", "brief": "my-post-2026-04-10-1430-brief.md", "postReview": "my-post-2026-04-10-1430-post-review.md", "reviewFindings": "my-post-2026-04-10-1430-review-findings.md", "postFixes": "my-post-2026-04-10-1430-post-fixes.md" } ``

snapshot suppression

Records the orchestrator's decision ledger: every finding both review agents produced, and what the orchestrator did with each. This is the Gap-F instrumentation: it makes visible whether a dropped suggestion was the reviewer proposing badly or the orchestrator filtering badly (opposite fixes). Invoked by the copydesk skill after it decides what to surface.

1. Write a suppression log to:

~/.claude/data/copydesk/learning/snapshots/{piece-filename}-{timestamp}-suppression.md

Use the same piece filename and timestamp as the matching post-review entry.

Record one row per finding from BOTH agents:

suppressed = the orchestrator neither surfaced it to the user nor silently fixed it (the dark-filter case). Be honest: log what was dropped, not only what was acted on.

1. Update the matching manifest entry to add a suppressionLog field with the filename.

Mode 2: Learning Analysis

Invoked directly by the user after they have finished manually editing a piece that was generated with copydesk.

Step 1: Load the minibatch

Read ~/.claude/data/copydesk/learning/snapshots/manifest.json.

If a file path was provided as an argument, the target is that single piece: match by piece name (derived from the path as in Mode 1; most recent by timestamp if several match).

If no file path was provided, load the last N unprocessed entries (default N=3) from the manifest: the minibatch. Every entry still in the manifest is unprocessed (cleanup removes processed ones in the last step). If fewer than N entries exist, use what's there.

For each piece in the minibatch, read its files:

• post-review snapshot: the postReview file
• post-fixes snapshot: the postFixes file
• brief: the brief file, if present (older snapshots may lack it)
• live edited file: if the user provided a path, read that file; otherwise determine the original output path from conversation context. If a batched piece has no locatable live file, fall back to its post-fixes snapshot.

If a piece's postFixes is missing, use its post-review snapshot as the post-fixes (the diff between post-review and the live file still captures everything).

Step 2: Load review findings and suppression logs

For each piece, read its reviewFindings file, and its suppressionLog file if present (the decision ledger from the live gate).

Step 3: Load accumulator

Read ~/.claude/data/copydesk/learning/accumulator.md. If it doesn't exist, proceed with an empty accumulator and tell the agent to use higher evidence thresholds (less prior evidence to cross-reference). The accumulator's Longitudinal Guidance section is PROTECTED context: pass it to the agent as read-only. The agent must not propose edits to it.

Step 4: Determine register(s)

Read the register field from each minibatch entry. A minibatch is normally single-register; if pieces span registers, note each piece's register so the agent can tag register-specificity correctly.

Step 5: Load current rules and held-out splits

Read these:

• The register file(s) for the batch: ~/.claude/data/copydesk/registers/{register}.md (includes the register's ## Demonstrated Edits exemplars)
• The skill file: ${CLAUDE_PLUGIN_ROOT}/skills/write/SKILL.md
• The prose review agent: ${CLAUDE_PLUGIN_ROOT}/agents/prose-review.md
• The craft review agent: ${CLAUDE_PLUGIN_ROOT}/agents/craft-review.md
• The held-out splits: ~/.claude/data/copydesk/learning/splits.md if it exists (defines the train / selection / test sets the gate uses). If absent, the gate falls back to retrospective checks on available snapshots.

Step 6: Dispatch the learning agent (the optimizer)

Use the Agent tool:

• subagent_type: "copydesk:learn-review"
• model: opus
• description: "Analyze edits and propose improvements"
• prompt: Include the per-piece inputs for all N pieces (clearly labeled by piece) plus the shared context once:

``` ## BATCH: N pieces

### Piece 1: {piece name} (register: {register}) #### Post-Review Snapshot [full text] #### Post-Fixes Snapshot [full text] #### Post-Manual-Edit (Live File) [full text] #### Compacted Review Findings [full text of review-findings file]

### Piece 2: {piece name} (register: {register}) [...same four sub-sections...]

(repeat for each piece in the batch)

## Shared context

### Current Register: {register name} [full text of the register file, including its Demonstrated Edits]

### Current SKILL.md [full text]

### Current Prose Review Agent [full text]

### Accumulator [full text, or "EMPTY -- no prior observations. Use higher evidence thresholds." The Longitudinal Guidance section is PROTECTED: do not propose edits to it.] ```

Wait for the agent to return its tiered findings (Apply / Hold / Reinforce / Contradictions), with Apply capped at L_t candidate edits.

Step 7: Present candidates and classify them

Show the agent's full analysis. "Hold" and "Reinforce" observations are shown for information only. "Contradiction" flags are shown for the user to resolve (optional, can be deferred).

For each Apply candidate edit, present the pattern name, target file, evidence table, and exact proposed edit (old/new text), and classify it:

• Discipline edit — targets an objective banned pattern: em-dashes, colon-for-inline-elaboration, the banned-phrase / ChatGPT-ism list, caps-on-phrases, or the fatal-pattern. Gated by the discipline script (and the fatal-pattern re-checker), no human input.
• Taste edit — changes voice, craft, structure, or word choice in a way no script can score. Gated by the human pairwise step.

An edit can be both; if so it must pass both fractions.

Step 8: Gate each candidate edit

The gate decides what lands. An edit is applied only if it strictly passes its fraction(s). Freeze the reviewers and the discipline script for the duration of the gate so scores stay comparable (improve evaluators separately; see the evaluators mode).

Discipline fraction (objective, automatic). For a discipline edit, take a before/after sample (a held-out selection piece regenerated under old-vs-new skill-state, or the candidate's own before/after text), write each to a temp file, and run:

python scripts/discipline_check.py --diff <before-file> <after-file>

Accept only if introduced_new is false (no new violation) and the targeted violation count dropped. The discipline gate is a regression guardrail, not a fitness function: never use it to minimize violations as an optimization target. That trains toward clean-but-lifeless prose.

Taste fraction (structured-subjective). For a taste edit, run the pairwise step (Step 9). Accept only if the human picks the edited (new-skill-state) version.

Record, per candidate: accepted or rejected, which fraction(s) ran, and the score delta (discipline) or pairwise pick (taste). Rejected candidates feed the Rejected Edits buffer (Step 11).

Step 9: The pairwise step (human taste gate + shadow judge)

For each taste edit being gated: