← back to Cli Printing Press

fix(skills): keep scratch artifacts out of repo docs (#247)

d14cefaae705cb5fc51bd426e6ddc1b1bdbd80e2 · 2026-04-23 02:31:20 -0700 · Trevin Chow

Route retro scratch copies and transient skill artifacts through managed temp paths so public skills do not assume users have the Printing Press repo checked out. Also make publish/catalog staging collision-resistant with mktemp.

Files touched

• M skills/printing-press-catalog/SKILL.md
• M skills/printing-press-publish/SKILL.md
• M skills/printing-press-retro/SKILL.md
• M skills/printing-press-retro/references/issue-template.md
• M skills/printing-press/SKILL.md

Diff

commit d14cefaae705cb5fc51bd426e6ddc1b1bdbd80e2
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Thu Apr 23 02:31:20 2026 -0700

    fix(skills): keep scratch artifacts out of repo docs (#247)
    
    Route retro scratch copies and transient skill artifacts through managed temp paths so public skills do not assume users have the Printing Press repo checked out. Also make publish/catalog staging collision-resistant with mktemp.
---
 skills/printing-press-catalog/SKILL.md             |  7 +++-
 skills/printing-press-publish/SKILL.md             | 16 ++++++--
 skills/printing-press-retro/SKILL.md               | 47 ++++++++++++++--------
 .../references/issue-template.md                   |  7 ++++
 skills/printing-press/SKILL.md                     | 14 +++++--
 5 files changed, 67 insertions(+), 24 deletions(-)

diff --git a/skills/printing-press-catalog/SKILL.md b/skills/printing-press-catalog/SKILL.md
index 952923ae..3966d156 100644
--- a/skills/printing-press-catalog/SKILL.md
+++ b/skills/printing-press-catalog/SKILL.md
@@ -132,7 +132,10 @@ When invoked with `install <name>`:
 4. Show preview: "Installing <display_name> CLI from <spec_url>"
 5. Download the spec and generate:
    ```bash
-   curl -sL -o /tmp/catalog-spec-$$.yaml "<spec_url>"
+   CATALOG_TMP_DIR="/tmp/printing-press/catalog"
+   mkdir -p "$CATALOG_TMP_DIR"
+   SPEC_TMP="$(mktemp "$CATALOG_TMP_DIR/<name>-spec-XXXXXX.yaml")"
+   curl -sL -o "$SPEC_TMP" "<spec_url>"
    OUTPUT_BASE="$PRESS_LIBRARY/<name>-pp-cli"
    OUTPUT_DIR="$OUTPUT_BASE"
    i=2
@@ -141,7 +144,7 @@ When invoked with `install <name>`:
      i=$((i + 1))
    done
    printing-press generate \
-     --spec /tmp/catalog-spec-$$.yaml \
+     --spec "$SPEC_TMP" \
      --output "$OUTPUT_DIR" \
      --validate
    ```
diff --git a/skills/printing-press-publish/SKILL.md b/skills/printing-press-publish/SKILL.md
index c8f9df71..19cae8a9 100644
--- a/skills/printing-press-publish/SKILL.md
+++ b/skills/printing-press-publish/SKILL.md
@@ -318,11 +318,14 @@ MODULE_PATH="<module_path_base>/<category>/<api-slug>"
 
 For example: `github.com/mvanhorn/printing-press-library/library/productivity/notion`
 
-Run `publish package` with `--target` to stage the CLI into a temporary directory, then copy it into the publish repo:
+Run `publish package` with `--target` to stage the CLI into a unique temporary
+directory, then copy it into the publish repo:
 
 ```bash
-STAGING_DIR="/tmp/publish-staging-<api-slug>"
-rm -rf "$STAGING_DIR"
+PUBLISH_STAGING_ROOT="/tmp/printing-press/publish"
+mkdir -p "$PUBLISH_STAGING_ROOT"
+STAGING_PARENT="$(mktemp -d "$PUBLISH_STAGING_ROOT/<api-slug>-XXXXXX")"
+STAGING_DIR="$STAGING_PARENT/package"
 
 printing-press publish package \
   --dir <cli-dir> \
@@ -350,6 +353,13 @@ rm -f "$PUBLISH_REPO_DIR/library/<category>/<api-slug>/<api-slug>" "$PUBLISH_REP
 cd "$PUBLISH_REPO_DIR/library/<category>/<api-slug>" && go build ./...
 ```
 
+After the publish repo copy and build verification are complete, remove the staging
+directory:
+
+```bash
+rm -rf "$STAGING_PARENT"
+```
+
 Note: `staged_dir` uses the CLI name (e.g., `espn-pp-cli`) but the publish repo uses the API slug (e.g., `espn`). The copy step handles this rename.
 
 ## Step 7: Collision Detection & Resolution
diff --git a/skills/printing-press-retro/SKILL.md b/skills/printing-press-retro/SKILL.md
index 5d8fb07a..d08b0443 100644
--- a/skills/printing-press-retro/SKILL.md
+++ b/skills/printing-press-retro/SKILL.md
@@ -73,8 +73,9 @@ _scope_dir="$(cd "$_scope_dir" && pwd -P)"
 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"
+mkdir -p "$PRESS_MANUSCRIPTS" "$PRESS_LIBRARY" "$RETRO_SCRATCH_DIR"
 
 # Detect whether we're inside the printing-press repo
 IN_REPO=false
@@ -423,13 +424,23 @@ Write the full retro document using this template:
 - ...
 ```
 
-Save the retro to manuscript proofs (always):
+Save the retro to manuscript proofs (always) and to the temp retro scratch
+directory (always). Do not save retro documents under the source repo's
+`docs/retros/` directory; the skill must work the same way for users who do not
+have the repo checked out, and retro documents are issue artifacts rather than
+durable repo docs.
 
 ```bash
-RETRO_PROOF_PATH="$PRESS_MANUSCRIPTS/$API_NAME/$RUN_ID/proofs/$(date +%Y%m%d-%H%M%S)-retro-$CLI_NAME.md"
+RETRO_STAMP="$(date +%Y%m%d-%H%M%S)"
+RETRO_PROOF_PATH="$PRESS_MANUSCRIPTS/$API_NAME/$RUN_ID/proofs/$RETRO_STAMP-retro-$CLI_NAME.md"
+RETRO_SCRATCH_DIR="/tmp/printing-press/retro"
+RETRO_SCRATCH_PATH="$RETRO_SCRATCH_DIR/$RETRO_STAMP-$API_NAME-retro.md"
+mkdir -p "$(dirname "$RETRO_PROOF_PATH")" "$RETRO_SCRATCH_DIR"
 ```
 
-This must complete before Phase 6 Step 1 copies the manuscripts directory to staging.
+Write the full retro document to `$RETRO_PROOF_PATH`, then copy that file to
+`$RETRO_SCRATCH_PATH`. This must complete before Phase 6 Step 1 copies the
+manuscripts directory to staging.
 
 ## Phase 5.5: Plannable work units
 
@@ -480,9 +491,10 @@ Use judgment. A retro that found three things but all three are "this API has a
 auth scheme no other API uses" is not worth an issue. A retro that found one small
 template gap that would help every future CLI *is* worth an issue.
 
-If the issue is skipped, still save the retro locally (manuscript proofs + `docs/retros/`
-if in-repo), present the findings to the user, then jump directly to Phase 6 Step 6
-(present results — adjusted to show local-only paths) and Step 8 (offer next steps).
+If the issue is skipped, still save the retro locally (manuscript proofs +
+`/tmp/printing-press/retro/`), present the findings to the user, then jump
+directly to Phase 6 Step 6 (present results — adjusted to show local-only paths)
+and Step 8 (offer next steps).
 
 ## Phase 6: Package, upload, and present
 
@@ -519,14 +531,14 @@ via `AskUserQuestion`.
 Options:
 1. **Submit** — upload artifacts and create the issue
 2. **Let me review the files first** — I'll check the staging folder, then come back
-3. **Save locally only** — skip the issue, just save to manuscripts
+3. **Save locally only** — skip the issue, keep the manuscript proof and temp copy
 
 If the user picks "Let me review the files first," acknowledge and wait. When they
 come back, re-ask with Submit / Save locally only.
 
-If the user picks "Save locally only," skip Steps 3 and 4 — save to manuscript
-proofs (and `docs/retros/` if in-repo), clean up the staging folder, then jump
-to Step 6.
+If the user picks "Save locally only," skip Steps 3 and 4 — the retro is already
+saved to manuscript proofs and `/tmp/printing-press/retro/`. Clean up the staging
+folder, then jump to Step 6.
 
 ### Step 3: Upload artifacts
 
@@ -543,14 +555,16 @@ document). Create the issue via `gh issue create --repo mvanhorn/cli-printing-pr
 If `gh` is not authenticated or issue creation fails, follow the graceful degradation
 path in the issue-template reference: save locally and print manual filing instructions.
 
-### Step 5: Local save (conditional)
+### Step 5: Local scratch copy
 
-If `IN_REPO=true`, also save the retro to the repo:
+Ensure the temp scratch copy exists. This is the human-friendly local path for
+reviewing or manually filing the retro when upload or issue creation fails.
 
 ```bash
-RETRO_DIR="$REPO_ROOT/docs/retros"
-mkdir -p "$RETRO_DIR"
-RETRO_FILE="$RETRO_DIR/$(date +%Y-%m-%d)-$API_NAME-retro.md"
+if [ -f "$RETRO_PROOF_PATH" ]; then
+  mkdir -p "$RETRO_SCRATCH_DIR"
+  cp "$RETRO_PROOF_PATH" "$RETRO_SCRATCH_PATH"
+fi
 ```
 
 ### Step 6: Present results
@@ -563,6 +577,7 @@ After the issue is created, show the user:
 >
 > Found <N> findings across <M> work units.
 > *(if artifacts uploaded)* Artifacts: [manuscripts](<URL>) · [CLI source](<URL>)
+> Local copy: <$RETRO_SCRATCH_PATH>
 
 If the issue wasn't created (user chose local-only, or gh failed), show the local
 save paths instead.
diff --git a/skills/printing-press-retro/references/issue-template.md b/skills/printing-press-retro/references/issue-template.md
index 5343499d..23f07dd1 100644
--- a/skills/printing-press-retro/references/issue-template.md
+++ b/skills/printing-press-retro/references/issue-template.md
@@ -145,6 +145,9 @@ if [ "$GH_AVAILABLE" = false ]; then
   echo "  1. Go to: https://github.com/mvanhorn/cli-printing-press/issues/new"
   echo "  2. Title: $ISSUE_TITLE"
   echo "  3. Copy the retro content from: $RETRO_PROOF_PATH"
+  if [ -n "$RETRO_SCRATCH_PATH" ] && [ -f "$RETRO_SCRATCH_PATH" ]; then
+    echo "     Temp copy: $RETRO_SCRATCH_PATH"
+  fi
   if [ -n "$MANUSCRIPTS_URL" ]; then
     echo "  4. Manuscripts: $MANUSCRIPTS_URL"
   fi
@@ -154,6 +157,9 @@ if [ "$GH_AVAILABLE" = false ]; then
   echo ""
   echo "The retro document has been saved locally to:"
   echo "  $RETRO_PROOF_PATH"
+  if [ -n "$RETRO_SCRATCH_PATH" ] && [ -f "$RETRO_SCRATCH_PATH" ]; then
+    echo "  $RETRO_SCRATCH_PATH"
+  fi
 fi
 ```
 
@@ -174,4 +180,5 @@ well under this for typical retros. If `gh issue create` fails with a body-size
 | `$MANUSCRIPTS_URL` | artifact-packaging.md | catbox URL or empty |
 | `$CLI_SOURCE_URL` | artifact-packaging.md | catbox URL or empty |
 | `$RETRO_PROOF_PATH` | SKILL.md Phase 5 | Path to saved retro in manuscript proofs |
+| `$RETRO_SCRATCH_PATH` | SKILL.md Phase 5 | Path to temp retro copy under `/tmp/printing-press/retro/` |
 | All retro findings | SKILL.md Phase 4 | The prioritized findings to populate tables |
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index e07ae27f..9320530f 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -87,7 +87,7 @@ See the `printing-press-polish` skill for details. It runs diagnostics, fixes ve
 - Optimize for time-to-ship, not time-to-document.
 - Reuse prior research whenever it is already good enough.
 - Do not split one idea across multiple mandatory artifacts.
-- All files produced by this skill go under `$PRESS_RUNSTATE/` (working state) or `$PRESS_MANUSCRIPTS/` (archived). These are the only writable locations.
+- Durable files produced by this skill go under `$PRESS_RUNSTATE/` (working state) or `$PRESS_MANUSCRIPTS/` (archived). Short-lived command captures may use `/tmp/printing-press/` and must be removed after use.
 - Do not create a separate narrative phase for dogfood, dead-code audit, runtime verification, and final score. Treat them as one shipcheck block.
 - Run cheap, high-signal checks early.
 - Fix blockers and high-leverage failures first.
@@ -338,12 +338,16 @@ Maintain a lightweight state file at `$STATE_FILE` so `/printing-press-score` ca
 
 Do not create a `go.work` file in `$CLI_WORK_DIR`. Generated modules must build and test as standalone modules; a mismatched workspace `go` directive can break Go 1.25+ toolchains and lefthook checks. Editor/gopls workspace noise is cosmetic and must not be traded for broken `go build` or `go test`.
 
-There are exactly three writable locations. Every file this skill produces goes to one of them:
+There are exactly three durable writable locations. Every generated artifact this
+skill preserves goes to one of them:
 
 - **`$PRESS_RUNSTATE/`** — mutable working state for the current run (research, proofs, pipeline artifacts, plans, intermediate docs)
 - **`$PRESS_LIBRARY/`** — published CLIs (`<api-slug>/` subdirectories)
 - **`$PRESS_MANUSCRIPTS/`** — archived run evidence (research, proofs, discovery)
 
+Short-lived command captures may use `/tmp/printing-press/` with unique `mktemp`
+paths and must be deleted after use.
+
 Examples of the current naming/layout:
 - `~/printing-press/library/notion/` — published CLI directory (keyed by API slug)
 - `notion-pp-cli` — the binary name inside the directory
@@ -1893,9 +1897,13 @@ Do NOT proceed without asking. Do NOT substitute an ad-hoc smoke test. If some c
 **Critical: pipe-free exit-code checks.** A shell command like `"$BIN" foo | tail -2` captures `tail`'s exit code, not the binary's. Always run as:
 
 ```bash
-"$BIN" <subcmd> <args> > /tmp/out 2>&1
+DOGFOOD_TMP_DIR="/tmp/printing-press/dogfood"
+mkdir -p "$DOGFOOD_TMP_DIR"
+OUT_FILE="$(mktemp "$DOGFOOD_TMP_DIR/<api>-out-XXXXXX")"
+"$BIN" <subcmd> <args> > "$OUT_FILE" 2>&1
 code=$?
 # then check $code directly
+rm -f "$OUT_FILE"
 ```
 
 Never use `"$BIN" ... && echo ok || echo fail` for exit-code testing — short-circuit and unpredictable piping masks real failures.

← e741db80 feat(cli): generate replayable website CLIs (#241)  ·  back to Cli Printing Press  ·  fix(ci): allow release-please PR title scope (#248) bc13a5b4 →