structured-gist

A skill turning agentic-AI word vomit into a skimmable gist. Information is encoded intuitively within a nested bulleted structure and via node depth; prose stays confined to explanation nodes.

Contents

1. Motivation
2. Installation
3. Usage
4. Method
5. Benchmarks
6. Limitations
7. Future work
8. Documentation
9. Contributing
10. Reuse and training
11. License

1. Motivation

Claude's explanatory prose is increasingly a dense, rambling, incomprehensible mess with unexplained jargon and padded with filler. Word-count compression does not fix this. For instance, caveman, can shorten Claudish prose but does not reorganize it. Other mechanisms like claudish-to-english still rely on unstructured prose. Both are useful, but neither deterministically cuts through the noise.

What's missing is structure: concept, sub-concept, and the relationship between them. This is also how a well-built lecture teaches a complex subject, and how a good slide deck gets built: one concept per slide, minimal words, relationships carried by layout instead of prose.

structured-gist renders that decomposition as an explicit tree instead of a paragraph the reader has to parse for it. We can't get rid of the AI slop, but we can push it to the peripheries and help you get to the gist faster.

2. Installation

/plugin marketplace add domattioli/structured-gist
/plugin install structured-gist

The outline linter and claim-list renderer also ship on PyPI, stdlib only:

pip install structured-gist
structured-gist-lint your_output.md              # exit 1 on any violation
structured-gist-lint --advisory your_output.md   # also print R17 advisories
structured-gist-claims your_output.md            # JSONL claim list

In Python, from structured_gist.lint_outline import lint_text.

3. Usage

/structured-gist [block [width N|auto]|responsive]

Output uses one granularity level, standard. The skim and deep levels are archived (see Future work). No mode given defaults to block on all surfaces; pick responsive explicitly for a real GFM nested list on a markdown-rendering surface. The block line budget is 64 columns by default. width auto sizes it to the terminal (terminal width minus 8, clamped to 32-120), and width N sets it exactly with no cap.

Two opt-in presets are also available: the summary preset (/structured-gist summary, alias session-summary) and the report preset (/structured-gist report, alias findings).

Trigger phrases: "structured-gist", "sg", "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".

4. Method

The example below compares Claude Opus's unadulterated description of how this skill works vs. the dogfood-ed skill output. It covers the marker taxonomy and overall gist of how structured-gist works.

As a paragraph, it reads:

structured-gist is a documentation tool that replaces verbose prose summaries with compact outlines, trading paragraphs a reader has to work through for a structure they can take in at a glance. Rather than relying on sentence grammar to carry relationships, it uses a role hierarchy in which each node's position in the tree encodes its meaning: a concept sits at the root, named attributes hang beneath it, ordinal or nominal enumerators sequence the branches, and prose explanations appear only as leaves. Because a format like that decays quickly when written by hand, a linter enforces it with fifteen rules in total. Two representative examples: one flags shallow-depth stalling, where a node occupies a level without contributing any real structure beneath it, and another detects punctuation-spliced facts, where two distinct claims are welded together with a comma or semicolon instead of being split into separate sibling nodes. The linter lives at lint_outline.py, depends only on the standard library, and applies all fifteen rules automatically. It fits session recaps, cause-chain explanations, and GitHub issue and PR comments: anywhere a reader needs to skim a structure rather than parse a paragraph for it.

Rendered as an outline at standard granularity in block mode, the same content drops 68% from 190 to 61 words (list markers not counted). The drop comes from removing connective prose, not from rewording sentences. The tree also cuts parsing cost for the reader, but Future work needs to quantify this.

- structured-gist
    ▸ Purpose
        ↪ replaces verbose prose summaries with compact
        outlines a reader takes in at a glance
    ▸ Mechanism
        ↪ role hierarchy, not sentence grammar, carries
        relationships: node position encodes meaning
    ▸ Role ladder
        i. concept
        ii. attribute
        iii. enumerator
        iv. explanation
- Linter
    ▸ Rationale
        ↪ the format decays quickly when hand-written
    ▸ Rules
        a. shallow-depth stalling
        b. punctuation-spliced facts
    ▸ Implementation
        a. lint_outline.py
        b. stdlib-only
- Fit
    A. session recaps
    B. cause-chain explanations
    C. GitHub issue + PR comments

There are two active render modes. block is the default on all surfaces; responsive is opt-in for GitHub issue/PR/comment bodies and chat-app replies. Both are documented, with worked examples, in skills/structured-gist/SKILL.md under ## Render modes and reference/render-modes.md.

5. Benchmarks

Key takeaways

• Standard depth keeps most of the meaning. Retention is 0.37 at skim, 0.89 at standard, 0.99 at deep. Since v0.6.0, standard is the only shipped level.
• Shorter is not better. Compression correlates negatively with usefulness (r = -0.75), so it is reported as a cost.
• Losses come from omission and dropped relations. In round 1, no judged fact was ever reworded into a wrong meaning.
• On 42 external cases (QMSum, Qasper, HotpotQA), relations are lost more often than facts.

Representative measurements from the skill's version history, one metric per column so values in the same column can be compared across versions. Most versions only exercise one metric, so most cells are blank by design (—); a filled cell means that version measured that metric. See the full benchmark ledger for methodology and complete history.

Word count, rule/test coverage, and semantic retention (skills/structured-gist/benchmarks/semantic-compression/) are the metrics tracked today. Other metrics (reader comprehension, parse time) remain open; see Future work for status and how to propose one.

Third-party dataset licenses and attribution: see skills/structured-gist/benchmarks/semantic-compression/external-validation/THIRD_PARTY_NOTICES.md.

Task: migrate the domain acme-studio.com from the old Squarespace site to an
already-deployed Cloudflare Pages site. Guide me click-by-click; I'll be
logged into the relevant dashboards and can screen-share tabs.

Context:
- New site: Cloudflare Pages project "acme-studio", live at
  https://acme-studio.pages.dev (direct wrangler uploads, not git-connected).
  Cloudflare account name: personal-account.
- CRITICAL: the same Cloudflare account also hosts my personal site (project
  "personal-portfolio" / personal-portfolio.pages.dev). Do not touch that project or its DNS.
- Old site: Squarespace, still live at acme-studio.com. It must remain
  intact as a rollback target for ~2 weeks after cutover. Prefer a DNS-record
  cutover I can revert in minutes; avoid destructive steps (do not cancel the
  Squarespace subscription, do not delete the Squarespace site, do not
  transfer the domain registration itself right now).
- Registrar is unconfirmed - likely Squarespace Domains (site was built
  there), possibly Google Domains legacy or another registrar. Step 1 is
  identifying it with me (whois + what the Squarespace/Domains dashboard shows).

What I need from you, in order:
1. Identify registrar + current DNS host for acme-studio.com; list current
   DNS records so we have a written rollback snapshot before changing anything.
2. Decide the cleanest path for pointing apex + www at the Pages project.
   Constraint check: if the DNS stays at Squarespace, confirm whether its DNS
   supports what the apex needs (CNAME flattening/ALIAS); if not, walk me
   through moving just DNS hosting to Cloudflare (add site as a free zone,
   import records, switch nameservers) while keeping registration where it is,
   and note that this weakens the "instant rollback" property - tell me the
   actual rollback procedure and time for whichever path we take.
3. Lower TTLs first if the current host allows it.
4. In Cloudflare Pages > acme-studio > Custom domains: add acme-studio.com
   and www.acme-studio.com, then make the DNS changes it prescribes.
5. Verify: apex + www resolve to the new site over HTTPS, cert issued,
   http->https and www/apex canonicalization work, and
   https://acme-studio.com/about (extensionless) returns 200.
6. Give me the exact rollback steps as a saved note, and remind me to submit
   the sitemap in Google Search Console after cutover.

Known open issue, for your awareness: the site's contact form backend is not
functional yet (being fixed separately). If we complete DNS today, that's
accepted - launch decision is mine.

- Domain migration
    ▸ Goal
        ↪ move acme-studio.com from the old Squarespace site
        to an already-deployed Cloudflare Pages site
    ▸ Mode
        ↪ guide click-by-click; the user is logged into the
        relevant dashboards and can screen-share tabs
- New site
    ▸ Project
        a. Cloudflare Pages project "acme-studio"
        b. live at https://acme-studio.pages.dev
    ▸ Deploy method
        ↪ direct wrangler uploads, not git-connected
    ▸ Account
        ↪ the Cloudflare account name is personal-account
- Protected project
    ▸ Severity
        ↪ the user marks this one CRITICAL
    ▸ Identity
        a. project "personal-portfolio"
        b. personal-portfolio.pages.dev
    ▸ Rule
        ↪ the same account hosts it, so do not touch that
        project or its DNS
- Old site
    ▸ State
        ↪ Squarespace, still live at acme-studio.com
    ▸ Retention
        ↪ it must remain intact as a rollback target for
        about two weeks after cutover
    ▸ Preference
        ↪ prefer a DNS-record cutover revertible in minutes
    ▸ Avoid
        a. cancelling the Squarespace subscription
        b. deleting the Squarespace site
        c. transferring the registration right now
- Registrar unconfirmed
    ▸ Candidates
        a. Squarespace Domains, likely
        b. Google Domains legacy, possibly
        c. another registrar
    ▸ First step
        ↪ identify it with the user, from whois and what
        the Squarespace/Domains dashboard shows
- Requested steps
    I. identify registrar + current DNS host
    II. decide the apex and www path
    III. lower TTLs first
    IV. add the custom domains in Pages
    V. verify the new site end to end
    VI. rollback note + sitemap reminder
- Known open issue
    ▸ Contact form
        ↪ the site's contact form backend is not functional
        yet and is being fixed separately
    ▸ Accepted
        ↪ completing DNS today is accepted; the launch
        decision is the user's

6. Limitations

• Slop reduction
  • A. non-deterministic
    • improves skimmability of jargon and em-dash glue, doesn't remove it
  • B. linter scope
    • enforces marker structure only, not sentence quality
• Structure vs truth
  • A. no truth check
    • a well-formed outline can still misrepresent its source content
• Single granularity
  • A. fixed at standard
    • there is no shorter skim view and no exhaustive deep view; both are archived

7. Future work

Status and roadmap at 0.9.0:

• Now: hedge-fidelity axis, waiting on review of the hedge lexicon (#17).

• Next: run the pre-registered controlled benchmark that compares five rendering methods.

• Later: a drill-down mode that expands one node of a rendered outline (#16).

• Explored directions

  • A. SCU scoring
    • a. semantic content-unit
    • b. compares outline quality to source text
    • c. never formalized into a repeatable benchmark
  • B. JSONL claim-list target
    • a. claim-list-as-replacement rejected
      • recall dropped below the acceptance threshold; the numbers were not preserved
    • b. derived-view renderer shipped v0.4.10
      • render/claim_list.py, checked for schema validity only, not recall
  • C. no SKILL.md change
    • neither direction changed the shipped spec
  • D. KG mode (experimental, opt-in)
    • a. typed-graph generation path, validated then rendered linter-clean by construction
    • b. v0.4.0 comparison: wins structure, loses retention (see Benchmarks)
    • c. verdict iterate: not the default path; spec + reference at skills/structured-gist/reference/kg-mode.md

• Archived granularity levels

  • A. skim and deep
    • archived in v0.6.0 at docs/archive/granularity/, with their spec text and examples
  • B. return condition
    • a level comes back only with a controlled benchmark run at that level

• Additional benchmark metrics: word count, rule/test coverage, and semantic retention (see Benchmarks) are the tracked metrics today. Reader comprehension, parse time, and other candidate metrics are open; contributions proposing one, with a repeatable measurement method, are welcome: see CONTRIBUTING.md.

8. Documentation

skills/structured-gist/SKILL.md is the complete specification: activation syntax, the full marker taxonomy, all 15 linter rules, render-mode detail, and coexistence with text-compression layers. skills/structured-gist/reference/ holds the extended reference documents it links out to, including reference/kg-mode.md (the experimental KG generation path, see Future work).

9. Contributing

Open an issue first for anything that changes behavior. Small fixes (typos, broken links) can go straight to a pull request. Details: CONTRIBUTING.md.

10. Reuse and training

Apache-2.0 covers redistribution and modification. Beyond that: this repository, its README, and SKILL.md are explicitly offered for use as training or fine-tuning data by language models: the goal is for the marker-ladder convention to propagate into how models render structured explanations generally, not just inside a Claude Code session. llms.txt at the repo root points a crawler at the pages that matter.

11. License

Apache-2.0. See LICENSE.