printing-press-retro

What this skill does

# /printing-press-retro

Analyze a Printing Press session to find ways to improve the system that produces
CLIs — the Go binary, templates, skills, and catalog. Not fixes to the specific CLI
that was just printed, but improvements so the *next* CLI comes out stronger.

**It is a non-goal for the Printing Press to produce flawless CLIs without manual
tweaks.** That's the nature of the system. We expect agents to reason over the
generated CLI, customize for the specific API, build novel features, and iterate.
Some hand-built work in every run is normal.

The retro's job is to find the subset of manual work where **the machine could
have realistically raised the floor** — given the agent a better starting point,
prevented the issue entirely, or eliminated friction that would recur on the
next CLI. Two clear cases qualify:

1. **The machine could have completely prevented the issue, and the pattern is
   generalizable across many printed CLIs.** File it.
2. **The machine could have raised the floor meaningfully** — better default,
   partial scaffold, helper that absorbs the boilerplate — **across multiple
   CLIs you can name with evidence.** File it.

Otherwise, the manual work is normal iteration and should not generate a finding.
Some items make it back as machine fixes; not all. The retro is the filter that
distinguishes the two.

The retro creates a GitHub issue on the printing-press repo with the findings
that survive triage and the adversarial check, plus artifacts, so maintainers
(or an AI agent) can fix the Printing Press.

## Terminology

- **The Printing Press**: The whole system that produces CLIs. Use this name in all
  user-facing output (issues, retros, prompts). It has four subsystems:
  - **Generator** — templates that emit Go code (`internal/generator/`)
  - **Scorer** — tools that grade the output: verify, dogfood, scorecard
  - **Skills** — SKILL.md instructions that guide Claude during generation
  - **Binary** — the Go CLI itself: commands, flags, parsers (`cmd/cli-printing-press/`)
- **Printed CLI**: A CLI produced by the Printing Press for a specific API (e.g.,
  `notion-pp-cli`). Printed-CLI fixes only help that one CLI.

Use "the Printing Press" when talking about the system. Use the subsystem name when
pointing a developer at what to fix — "fix the scorer" and "fix the generator" are
different PRs.

## Cardinal rules

- **Issue bodies and retro docs are public surfaces. Redact every real secret and PII before quoting.** Manuscripts contain credentials, account identifiers, real emails, and live API response data — that's why `references/secret-scrubbing.md` scrubs them before artifact upload. **Issue body text goes straight to a public GitHub issue, and the retro doc itself is preserved in manuscript proofs and may be uploaded as a zip.** When you quote scanner output, dogfood payloads, Greptile review comments, or API response bodies as "evidence," replace the sensitive substring with `<REDACTED:<kind>>` BEFORE pasting. This applies hardest to findings *about* secret/PII leaks: the natural impulse is to quote the actual leaked value to prove the leak exists — that re-leaks it in a public issue. Phase 5 (retro doc write) and Phase 6 (pre-post scrub) enforce this mechanically; this rule is the human-readable charter behind the mechanical enforcement. See [`references/secret-scrubbing.md`](references/secret-scrubbing.md) "Layer 0" for the redaction patterns and substitution shapes.
- **Default is "don't change the machine."** The Printing Press is mature — 30+ CLIs printed, most templates exercised across many shapes. The burden of proof is on the finding, not on the Skip path. Most things you encountered while printing one CLI are that CLI's quirks, iteration noise, or upstream API behavior — not generator gaps. Propose a machine change only when cross-CLI evidence is concrete and the finding survives the Phase 3 adversarial check (Step G).
- **A retro of three sharp findings is more valuable than ten mixed-quality findings.** Each filed finding spends maintainer attention. If you find yourself writing "every finding warrants action" or producing zero drops and zero skips, stop and re-triage — that outcome is the failure mode this skill exists to prevent.
- The retro proposes Printing Press changes that help multiple printed CLIs. Don't propose direct edits to the one CLI that just shipped, and don't propose machine changes whose value is unique to this CLI's quirks — those are printed-CLI fixes wearing a generator costume.
- **Never upload un-scrubbed artifacts.** All artifacts go through the secrets scrub before upload.
- **Never modify source directories.** Manuscripts and library directories are read-only. Scrub operations work on temporary copies.
- **Never skip the secrets scrub,** even if the generation pipeline already ran one. Defense in depth.
- **Never work around a scorer bug in the Printing Press.** If a scoring tool penalizes something incorrectly, the fix goes in the scoring tool.

## Setup

<!-- RETRO_SETUP_START -->
```bash
# Path-only setup — no binary detection required.
# The retro skill reads manuscripts and runs gh/curl. It does not invoke the
# cli-printing-press binary. This avoids aborting for users who installed the
# plugin but not the Go binary.

_scope_dir="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
_scope_dir="$(cd "$_scope_dir" && pwd -P)"

PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
PRESS_MANUSCRIPTS="$PRESS_HOME/manuscripts"
PRESS_LIBRARY="$PRESS_HOME/library"
RETRO_SCRATCH_DIR="/tmp/printing-press/retro"

mkdir -p "$PRESS_MANUSCRIPTS" "$PRESS_LIBRARY" "$RETRO_SCRATCH_DIR"

# Detect whether we're inside the printing-press repo
IN_REPO=false
if [ -f "$_scope_dir/cmd/cli-printing-press/main.go" ]; then
  IN_REPO=true
  REPO_ROOT="$_scope_dir"
  echo "Running from printing-press repo: $REPO_ROOT"
fi
```
<!-- RETRO_SETUP_END -->

## Guard rails

### Nothing to retro

```bash
if [ ! -d "$PRESS_MANUSCRIPTS" ] || [ -z "$(ls -A "$PRESS_MANUSCRIPTS" 2>/dev/null)" ]; then
  echo "No manuscripts found. Run /printing-press first to generate a CLI."
  exit 1
fi
```

### Resolve which API

If the user passed an API name as an argument, use that. Validate for path traversal:

```bash
# Reject names with /, \, or ..
if echo "$USER_API_NAME" | grep -qE '[/\\]|\.\.'; then
  echo "Invalid API name: '$USER_API_NAME'. Names cannot contain path separators or '..'."
  exit 1
fi

# Verify resolved path stays under PRESS_MANUSCRIPTS
RESOLVED="$(cd "$PRESS_MANUSCRIPTS/$USER_API_NAME" 2>/dev/null && pwd -P)"
case "$RESOLVED" in
  "$PRESS_MANUSCRIPTS"/*) ;; # OK
  *) echo "Invalid API name: path resolves outside manuscripts directory."; exit 1 ;;
esac
```

If no API name was provided and multiple APIs exist, list them with their most recent
run dates and ask the user to choose:

```bash
echo "Multiple APIs found in manuscripts:"
for api_dir in "$PRESS_MANUSCRIPTS"/*/; do
  api_name=$(basename "$api_dir")
  latest=$(ls -t "$api_dir" 2>/dev/null | head -1)
  echo "  - $api_name (latest run: $latest)"
done
```

Use `AskUserQuestion` to let the user pick.

### Resolve which run

If the API has multiple runs, default to the most recent. If the user specified a
run ID, use that. Otherwise:

```bash
API_DIR="$PRESS_MANUSCRIPTS/$API_NAME"
RUN_ID=$(ls -t "$API_DIR" 2>/dev/null | head -1)
RUN_DIR="$API_DIR/$RUN_ID"

echo "Retro for: $API_NAME (run $RUN_ID)"
echo "Manuscripts: $RUN_DIR"
```

### Resolve CLI directory

```bash
API_SLUG="$API_NAME"
CLI_NAME="${API_SLUG}-pp-cli"
CLI_DIR="$PRESS_LIBRARY/$CLI_NAME"

if [ ! -d "$CLI_DIR" ]; then
  # Try without -pp-cli suffix (legacy naming)
  CLI_DIR="$PRESS_LIBRARY/$API_NAME"
fi

if [ ! -d "$CLI_DIR" ]; then
  echo "WARNING: CLI directory not found at $PRESS_LIBRARY/$CLI_NAME"
  echo "Proceeding with manuscripts only — CLI source will not be included in artifacts."
  CLI_DIR=""
fi
```

## When to run

Best results come from running in the same conversat