structured-gist

Files (200)

• CHANGELOG.md
• SKILL.md
• compare_corpus.py · benchmarks/
• content_units.py · benchmarks/
• PREREGISTRATION.md · benchmarks/controlled/
• README.md · benchmarks/controlled/
• __init__.py · benchmarks/controlled/bench/
• agents_inc_isolated.py · benchmarks/controlled/bench/
• baselines.py · benchmarks/controlled/bench/
• cache.py · benchmarks/controlled/bench/
• estimate.py · benchmarks/controlled/bench/
• generate.py · benchmarks/controlled/bench/
• items.py · benchmarks/controlled/bench/
• judge.py · benchmarks/controlled/bench/
• pacing.py · benchmarks/controlled/bench/
• pipeline.py · benchmarks/controlled/bench/
• prereg.py · benchmarks/controlled/bench/
• records.py · benchmarks/controlled/bench/
• score.py · benchmarks/controlled/bench/
• stopwords.txt · benchmarks/controlled/bench/
• words.py · benchmarks/controlled/bench/
• .gitkeep · benchmarks/controlled/launchd/
• prereg.json · benchmarks/controlled/
• bullets_instruction.md · benchmarks/controlled/prompts/
• judge.md · benchmarks/controlled/prompts/
• plain_system.md · benchmarks/controlled/prompts/
• prose_instruction.md · benchmarks/controlled/prompts/
• provider_notice.txt · benchmarks/controlled/prompts/
• shared_user.md · benchmarks/controlled/prompts/
• skill_instruction.md · benchmarks/controlled/prompts/
• run.py · benchmarks/controlled/
• judge-output.schema.json · benchmarks/controlled/schemas/
• records.schema.json · benchmarks/controlled/schemas/
• .gitkeep · benchmarks/controlled/slop/cases/
• __init__.py · benchmarks/controlled/tests/
• conftest.py · benchmarks/controlled/tests/
• fakes.py · benchmarks/controlled/tests/
• agents_inc_help.txt · benchmarks/controlled/tests/fixtures/cli/
• agents_inc_run_help.txt · benchmarks/controlled/tests/fixtures/cli/
• claude_help.txt · benchmarks/controlled/tests/fixtures/cli/
• claude_version.txt · benchmarks/controlled/tests/fixtures/cli/
• gask_usage.txt · benchmarks/controlled/tests/fixtures/cli/
• mask_usage.txt · benchmarks/controlled/tests/fixtures/cli/
• oask_usage.txt · benchmarks/controlled/tests/fixtures/cli/
• prompt_hashes.json · benchmarks/controlled/tests/fixtures/
• prereg_fixture.py · benchmarks/controlled/tests/
• test_cache.py · benchmarks/controlled/tests/
• test_items.py · benchmarks/controlled/tests/
• test_prereg.py · benchmarks/controlled/tests/
• test_prompts.py · benchmarks/controlled/tests/
• test_records.py · benchmarks/controlled/tests/
• test_run_cli.py · benchmarks/controlled/tests/
• test_runner.py · benchmarks/controlled/tests/
• test_words.py · benchmarks/controlled/tests/
• corpus.json · benchmarks/corpus/
• agentic-harness-explain.md · benchmarks/corpus/sources/
• boundary-formalization.md · benchmarks/corpus/sources/
• cause-chain-root-cause.md · benchmarks/corpus/sources/
• ff-metric-glossary.md · benchmarks/corpus/sources/
• ff-release-checklist.md · benchmarks/corpus/sources/
• …and 140 more

SKILL.md (first lines)

# structured-gist — hierarchical lecture-note output

Replace paragraph printouts (esp. "what I did + my reasoning" recaps) with a nested, easily skimmable outline. Concept, attribute, and enumerator nodes carry structure with terse content; the `↪` hook-arrow carries the prose explanation (usually a branch leaf). Marker type conveys meaning on a fixed depth-ladder — never random. Structure only — wording untouched (independent of caveman).

Full detail beyond this file lives in `reference/` — this file is the ~2-minute read; each `## ` section below links out where there's more.

## Activation

On-demand: `/structured-gist [block [width N|auto]|responsive]`. One granularity level, `standard` (see `## Granularity`). No mode → `block` (default, all surfaces) — override explicitly with `responsive` when a GitHub issue/PR/comment body or chat-app reply needs a real GFM nested list instead of a fenced block. `width` sets the block-mode R11 line budget. Resolution order, first match wins: (1) explicit `width N` or `width auto`; (2) the width the consumer repo's AGENTS.md pins for that surface; (3) for terminal replies only, the host's terminal-width hint (`term_cols=N`), resolved as `auto`; (4) 64. `auto` resolves to clamp(N−8, 32, 120), where N is the terminal width in columns. An explicit `width N` is used as given, with no cap. Files, committed fences, and tool-posted bodies (issue, PR, and comment bodies) skip the hint and use 64 unless a width is set explicitly or pinned. `STRUCTURED_GIST_WIDTH` is the linter's default knob; the model does not read it. See `## Render modes`.
Lexicon triggers: "structured-gist", "sg", "in structured-gist", "gist mode", "gist this", "outline this", "bullet this", "notes mode", "structure this", "break this down", "distill this", "give me the gist", "make this skimmable", "tighten this up", "condense this" (+ optional mode word).
Elevatable: repo repository instructions may mandate as session default (+ default mode), like caveman.
Off: "stop structured-gist" / explicit prose request.

**Session-summary preset (v0.3): `/structured-gist summary` (alias `session-summary`).** A standalone invocation that emits a session-summary / handoff-shaped outline in one call, without the caller specifying structure — a quick end-of-session recap. It is self-contained (does NOT call the `handoff` skill; `handoff` is the fuller session-end retro, this is the terse inline outline). Canonical shape — the handoff sections are `-` concepts, their contents are `▸` attributes / enumerators / `↪` leaves:

```text
- Session summary
    ▸ Changed
        a. <area> — <what changed>
    ▸ Decisions
        ↪ <decision + one-line rationale>
    ▸ Next
        i. <ordered next step>
    ▸ State
        a. branch <name>
        b. PR <#/status>
    ▸ Open questions
        ↪ <question still unresolved>
```

(Enumerators under a `▸` attribute sit at depth 2, so they take the lowercase family — `a.`/`i.` — per the depth-keyed ladder below; the `▸` occupies depth 1.)

**Preset-omission contract (applies to every preset below).** A preset supplies optional branch names, not required slots — omit any branch the source does not support, the summary preset included. A preset never changes the marker ladder or adds a role.

**Report preset (v0.5.0b1): `/structured-gist report` (alias `findings`).** A standalone, finding-first invocation: one top concept per supported finding, multiple findings allowed as peers — never one packaging root. A finding is never invented when the source establishes none. Optional branches — Question, Method, Observed, Inferred, Next — are included only when source-supported; omit the rest per the preset-omission contract above. No generic Intro/Background/Conclusion heading — context stays nested under the finding it belongs to. Under Method, ordered steps take the lowercase ordinal family (`i.`/`ii.`) and unordered components the lowercase nominal family (`a.`/`b.`); Method itself is a named `▸` branch, never an ordinal node. Granularity and render mode apply unchanged; no new marker roles are introduced.

```text
- <finding>
    ▸ Method
        ↪ <how it was checked>
    ▸ Observed
        a. <what was seen>
    ▸ Next
        ↪ <follow-up action>
```

**Activation is verify-don't-assume (same bar as caveman).** Attempt the real Skill call (`/structured-gist`, or the mode in effect) — do not assume it loaded. On success, state so. On `Unknown skill` (skill not loaded at container start), emit exactly one line — `structured-gist NOT loaded → emulating from SKILL.md` — then apply the outline rules manually from this file. NEVER claim "structured-gist active" without a successful Skill call; a false claim of this exact form shipped in a session recap on 2026-06-27. The missing skill never blocks the turn — emulate and continue.

**Recommended: pair with a Stop-hook activation nudge, not a blocking gate.** A model can simply forget to invoke structured-gist on a long recap/explanation — there is no in-session signal forcing the check. The fix is advisory, not blocking: a Stop hook that reads the session transcript, and if the final assistant turn is long (word-count heuristic) AND no `Launching skill: structured-gist` backed call appears anywhere in the transcript, emits one stderr nudge line. It never blocks the turn — same fail-open contract as every other advisory hook (judgement-class checks are Stop advisories, not CI-hard gates). A consumer repo wiring this hook should model it on `stop_structured_gist_activation_guard.sh` alongside a claim-vs-call guard (audits false activation *claims*) and a rule-compliance guard (audits outlines already emitted) — three independent Stop-hook checks, not overlapping: claim-vs-call, output-quality, and activation-was-skipped. Cron-silent (`CLAUDE_INTERACTIVE=1` gate) and fail-open on missing jq/python3/transcript is the recommended contract. A hook cannot itself invoke the `Skill` tool (hooks are shell, not model turns) — it can only nudge the next turn's model into doing so; a blocking variant (exit nonzero to force another turn) was considered and rejected as unnecessarily coercive for a judgement-class check. This skill ships no hook scripts. The activation-nudge guidance above is for a consumer repo's own `.claude/hooks`.

## When — primary target

Default-render as outline when active:
- agent **process/recap prose** — "what I did and why" (the main case)
- explanations — concept / system / trade-off / cause-chain

NOT only on explicit "explain X". NOT on the carve-outs below.

## Marker taxonomy

**Consistent depth-ladder — marker type conveys meaning, never random.** Deepen one rung per nesting level; never skip rungs. A rung is a depth level, not a role: a concept may parent an enumerator directly (concept → enumerator is valid), with no attribute between them. **No plain bullet** — parts, steps, and evidence are all enumerable, so every sub-item enumerates.

The role ladder, outer to inner: **Concept → Attribute → Enumerator → Explanation.** Each answers a different question about its parent, so each has its own marker.

| role | marker | answers | word budget |
|---|---|---|---|
| **concept** | `-` (L1 only) | "what is this?" — a top concept, claim, or outcome | ~≤3 words |
| **attribute** | `▸` | "what does the parent *have*?" — a named property of the parent | ≤4 words |
| **enumerator** | `I. II.` / `A. B.` at **depth 1** · `i. ii.` / `a. b.` at **depth ≥2** | "the parent is *composed of* these ordered/grouped parts" | ≤6 words deep tiers |
| **explanation** | `↪` (hook arrow) | "what needs explaining or qualifying about the parent?" (e.g. why / how) — the one LONG prose sentence | no cap |

Who/what/where/when/why/how/whether are content prompts, not marker selectors — asking "why" does not pick `↪` by itself. Match by the role criteria above instead: top claim → concept, named property → attribute, ordered or grouped part → enumerator, explanation → `↪`.

**Attribute vs. enumerator (the distinction).** If a child reads naturally as "the parent *has a* ___" — a purpose, a component, a constraint, a property — it is an **attribute** (`▸`), not an enumerator. Enumerators are for genuinely ordered or grouped *parts/steps/evidence*. Rendering an attribute as a sibling `-` concept (flattening) or as an enumerator (mislabeling it a part) both lose the parent-attribute relation; `▸` preserves it. Example: "Marker ladder" is an attribute *of* structured-gist (`▸ Marker ladder`), not a peer concept and not a step.

**Ordinal vs nominal** picks the enumerator family, by the content:
- **ordinal** (roman: `I.`/`i.`) when ORDER matters — a sequence, steps, a ranking.
- **nominal** (letter: `A.`/`a.`) when items are distinct GROUPED peers, order-agnostic.

Attributes are inherently nominal (a property has a name, not a position) — there is no ordinal `▸` variant.

**Advisory attribute-name lexicon (not linter-enforced).** Names commonly source-supported: Purpose, Mechanism, Actor, Location, Timing, Certainty. Scope names a boundary and Trigger names an initiating condition — neither is a catch-all for every "where" or "when". "Whether" names a proposition to resolve, not a degree of confidence; a degree of confidence is Certainty. Prefer the source's own property names over this list, and omit any name the source does not support — this vocabulary is advisory guidance, not something the linter checks.

**A `▸` occupies a depth rung like any marker.** Enumerators directly under a concept sit at depth 1 (uppercase `I.`/`A.`); enumerators directly under a `▸` attribute sit at **depth 2**, so they take the lowercase family (`i.`/`a.`) — the ladder is keyed by absolute depth, not by "first enumerator encountered." (Linter rule R1.)

A child-set is one family — never mix `I.` and `A.`, or `▸` and an enumerator, as siblings. Emit literal glyphs (GFM collapses real ordered lists to `1.`). Indent rule: see `## Spacing`.

**No-self-nesting (never nest a marker directly under the same marker).** Concepts live only at L1 and enumerators already alternate roman↔letter by depth, so neither can self-nest; the rule bites on attributes: **a `▸` MUST NOT be the direct child of a `▸`.** To express a property-of-a-property, interpose a different node type — a non-leaf `↪` hook (see below) or an enumerator — never `▸`→`▸` directly. Linter rule R8.

**Leaf marker is `↪` (hook arrow), NOT `→`.** The plain `→` is reserved for inline cause-effect (`X → Y`) inside a node's text — the caveman wording convention — so it MUST NOT appear as a marker. `↪` always starts its own indented line (structure); `→` only ever sits mid-line (wording). Distinct glyphs, distinct jobs.

**Preserve source relation wording.** Keep the source's own relation wording and keep its endpoints identifiable. An association, correlation, or uncertain link is not rewritten as a causal `→`.

## Length gradient

Word budget — terse by default at EVERY level (recursive):
- every enumerator node = terse **concept** (denotes, does not explain); it embeds its meaning in hierarchy + short content, NOT prose
- higher tiers = fewest words; deeper nodes MAY use a few more *only when needed*
- the long explanatory sentence does NOT sit in an enumerator node → it rides a `↪` leaf
- a shallow node wordier than its own descendants = anti-pattern

**Connective-clause test (any depth).** A node carrying a reasoning connective — `because`, `since`, `so that`, `given that`, `as a result`, `which means`, or a parenthetical doing the same job (`(…, never verified against …)`) — is two nodes wearing one marker. Split it: the claim stays on the enumerator node; the reasoning moves to a `↪` child. This applies at L1 same as any deeper rung — a summary/`Net assessment`-style top bullet is not exempt just because it sits high in the tree.

**Delimiter-split test (R9, any depth).** The same split is forced by *punctuation*, not just connective words. A structural node — concept `-`, attribute `▸`, or enumerator — that appends content after a **spaced dash** (` - ` / ` — `), a **colon**, a **semicolon**, an **arrow** `→`, or inside a **parenthetical** `(…)` is two nodes wearing one marker — **unless the tail is only 1–2 words** (a terse qualifier like `scope: user dir` or `(default)` stays inline). When **>2 words** follow the delimiter, split: the head stays on the node, the tail drops to a nested child — a `↪` leaf when it explains, an enumerator when it is a genuine part. Exemptions: the `↪` leaf itself (the prose home — a colon/dash/arrow *inside* a `↪` sentence is fine), **intra-word hyphens** (`lecture-note` is one word, not a delimiter — only a space-flanked dash counts), inline code (`` `file:line` `` never counts), and **HTML entities** (`&amp;` / `&#x27;` — the trailing `;` is not a prose semicolon). Linter rule R9. A *chained* mid-line `→` (`X → Y; Z → W`) packs multiple facts under one marker and trips R9 the same way, while a **single** `X → Y` causality idiom (≤2-word tail) stays exempt — worked before/after: `examples/splice-to-subtree.md`.

**Double-marker test (R10, any depth).** A node's *content* must not begin with a second marker glyph. Emitting `▸ • target` or the terminal-rendered `- • target` (dash concept + bullet) or `- → foo` puts two markers on one line — the exact defect that made a fresh emulation render un-skimmable in a plain terminal (no markdown to collapse the leading `-`) while the same outline was clean in the Claude Code app. Pick ONE marker per node from the depth-ladder; never prefix the content with `•`, `→`, `↪`, `▸`, or another `-`. This bites emulation most: when the skill is not loaded and you render from this file by hand, indent with spaces and lead with a *single* ladder glyph — do not fall back to markdown `-`/`•` bullets. A mid-text causality arrow (`X → Y` inside a node) is fine — R10 fires only on a *leading* stray glyph, so the caveman single-arrow idiom is preserved. Arrow (`↪`/`→`) markers are the one legitimate leading glyph and are exempt. Linter rule R10.

## Hook-arrow `↪` — the explanatory node

- `↪` is the ONLY place prose explanation lives — enumerator + attribute nodes carry meaning by structure + terse content
- **usually a leaf** — one key cause-effect / elaboration per branch, rare, not every line
- **may be a non-leaf branch-summary** (v0.3): an `↪` MAY carry deeper children when it previews the subtree below it — a one-line "here's the gist, detail follows." A non-leaf `↪` MUST be the **first child** of its parent (a summary precedes the detail it introduces); an `↪` placed after its siblings stays a leaf. Linter rule R4.
- **subtree-preview guideline** — use a non-leaf `↪` only when the branch genuinely benefits from a one-line orientation before the reader descends, OR as the interposer that lets an attribute nest under another attribute without `▸`→`▸` (the no-self-nesting escape hatch). Do not summary-preview every branch; that reinflates the outline back toward prose.
- always starts its own indented line; never glued mid-line (that is the plain `→` inline-causality role, which `↪` deliberately does not share)
- **not caveman-compressed** — even when enumerator wording is compressed, the `↪` explanation stays a full, readable clause

## Nest by dependency

- a child **belongs-to / depends-on** its parent → a real tree, not a flat list dump

From domattioli/structured-gist, Apache-2.0.