diff --git a/skills/pst/REFERENCE.md b/skills/pst/REFERENCE.md index 95e3e0c..9d89d04 100644 --- a/skills/pst/REFERENCE.md +++ b/skills/pst/REFERENCE.md @@ -358,3 +358,46 @@ The Stage 0 Haiku classifier owns this decision. It returns `trivial` only on a approval, or hand off merge-ready (rule 5, merge-guard enforced). 7. If not gated pre-merge, validate locally before any remote promotion (rule 8). 8. Run `pst-worktrees.rb` and offer to prune orphaned worktrees (rule 4). + +## Rule 25 -- Context hygiene and output compression + +**Provenance:** inspired by [headroom](https://github.com/headroomlabs-ai/headroom), a context-compression research project. + +### Pre-execution output limiting + +Before running bash commands that may produce large output, append limiting flags: + +| Scenario | Limiting flag | +| ----------------- | -------------------------------------------- | +| `git log` | `git log --oneline -20` | +| `find` | `find . -name "*.rb" \| head -50` | +| `cat` large file | Use `Read` with `offset`/`limit` instead | +| JSON API response | `jq '{keys: keys, sample: .[0:2]}'` | +| Log file | `grep -E 'ERROR\|WARN' app.log \| tail -100` | + +### Content-type routing + +| Content type | What to extract | +| ------------ | ---------------------------------------------------------------- | +| JSON | Schema shape + key fields + item count | +| Logs | Errors and warnings first; summary of rest | +| Code | Read with `offset`/`limit`; avoid full-file reads on large files | +| Prose / docs | Key points only; skip boilerplate | + +### CCR pattern (Compress-Cache-Retrieve) + +For large intermediate artifacts that must persist across agents: + +1. **Compress:** distill to the minimum needed (schema, summary, key facts). +2. **Cache:** write to the session scratchpad directory with a descriptive filename (e.g. `schema-users-table.json`). +3. **Retrieve:** downstream agents use the Read tool on that path; pass the path in the agent prompt. + +This avoids re-passing large blobs through the context chain; the scratchpad persists for the session lifetime. + +### Cache-preservation note + +Anthropic's prompt cache keys on an exact contiguous prefix. Mutating or compressing earlier messages in an active session invalidates the cache from the first changed token onward. Compression helps future turns by keeping the context smaller; it does not preserve the current cached prefix. Only append to an active session; do not rewrite earlier content. + +### Verbosity-at-tail + +Put the most load-bearing instruction last in a long prompt -- models weight the tail of a prompt more heavily. In practice: lead a response with the actionable summary; put verbose output, debug traces, and raw data at the end. This is a drafting heuristic, not a guarantee. diff --git a/skills/pst/SKILL.md b/skills/pst/SKILL.md index f2a4376..7bf4940 100644 --- a/skills/pst/SKILL.md +++ b/skills/pst/SKILL.md @@ -113,7 +113,7 @@ rules a hook reminds about (non-blocking). Detail and examples are in merge mode. Arm with `pst-mode.rb local on`; bootstrap resets it each invoke. Override once with `PST_ALLOW_REMOTE=1`. 19. **Three-agent sequence for features and fixes** `[NUDGE]`. For any feature implementation or bug fix, run this pipeline. Haiku helper stages handle discovery, compression, scaffolding, cleanup, and the commit message around the three thinking tiers (Opus plan, Sonnet implement, Opus validate). Skip the whole pipeline only on a clear rule-2 trivial match; the Stage 0 classifier makes that call. 0. **Haiku classifier** (background, `model: haiku`, `effort: low`): read the request and return `trivial` or `substantive` plus a rationale (80 chars max). Trivial means a clear rule-2 Haiku-tier match; anything else or any doubt is `substantive`. On `trivial`, skip stages 0.5 through 4.5 and handle directly. Schema and sample prompt in `REFERENCE.md`. - 0.5. **Haiku pre-flight** (background, `model: haiku`): scout the repo (directory tree, recent git log, relevant file contents) and hand the Opus planner a compact context bundle so Opus tokens go to reasoning, not discovery. + 0.5. **Haiku pre-flight** (background, `model: haiku`): scout the repo (directory tree, recent git log, relevant file contents) and hand the Opus planner a compact context bundle so Opus tokens go to reasoning, not discovery. Apply Rule 25 heuristics when assembling the bundle: limit bash output, route by content type, and skip routing for tool output under ~50 lines. 1. **Opus planner** (background, `model: opus`, `effort: high`): produce a concrete, step-by-step implementation plan with file targets and acceptance criteria, using the pre-flight bundle as context. 1.5. **Haiku distiller** (background, `model: haiku`): compress the Opus plan into a 320-character exec summary for the plan gate. Haiku compresses; Opus thinks. 2. **Plan gate**: foreground `AskUserQuestion` presents the distilled summary (320 characters max). Up to two additional questions if needed. Proceed only on approval; treat no objection as approval. @@ -137,6 +137,8 @@ rules a hook reminds about (non-blocking). Detail and examples are in 24. **Best-of-N implementation tournament** `[NUDGE]`. For substantive refactors or extensions where multiple valid implementations exist, spawn 2-5 parallel Sonnet agents in isolated worktrees with divergent strategies, then have an Opus judge pick the winner using MAINTAINABILITY.md criteria. Skip for trivial one-way fixes. Rule 15 two-hats applies. `/pst:refactor` is the full implementation protocol. +25. **Context hygiene and output compression** `[NUDGE]`. Before any bash command that could produce large output, append limiting flags (`| head -N`, `--max-count`, `--limit`, etc.) to prevent context flooding. Route tool output by content type: JSON -> schema + key fields only; logs -> errors/warnings first, then summary; code files -> use Read with offset/limit; prose -> summarize key points. Skip routing for tool output under ~50 lines. Stage 0.5 pre-flight (rule 19) is the primary application point: apply these heuristics when assembling the context bundle handed to the Opus planner. + ## Usage `/pst` activates, `/pst off` disarms. Mechanics, merge modes, and rule detail are