# Findings

> Populate, extend, refresh, or audit a project's docs/findings.md — a curated index of headline empirical findings and interpretations with confidence tags and standardized source footers. Use when the user wants to draft a new findings doc, append new entries from recent build artifacts or audit JSONs, refresh load-bearing numbers against the current data, or check completeness.

- Skill: `hsigstad/findings` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hsigstad/findings`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hsigstad/findings/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: hsigstad (https://skillmd.com/u/hsigstad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hsigstad/findings

---


# /findings — Populate docs/findings.md

Draft, extend, refresh, or audit a project's `docs/findings.md`:
the curated index of *what we have learned* that the project considers
load-bearing for the paper or for downstream interpretation. Each entry is
a confidence-tagged headline with an expanded explanation, anchored to
build artifacts, reports, news, and cross-references through a
standardized Sources footer.

This skill is the *authoring* counterpart to `/findings-audit` (which
audits findings against external evidence — different verb). Use
`/findings` to write or maintain entries; use `/findings-audit` to
stress-test the entries you've written.

## Arguments

- `/findings` — infer project from cwd; default to populate-or-extend mode.
- `/findings <project-slug>` — run against a specific project under `projects/`.
- `/findings --extend` — preserve existing entries; only append new ones suggested by recent build artifacts, audit JSONs, or the user's pointer.
- `/findings --refresh` — recompute the load-bearing numbers in entries against current build artifacts; flag entries whose headline numbers don't match the current data. Critical for catching staleness after pipeline reruns or parser fixes.
- `/findings --audit` — do not write; report completeness gaps (missing source classes, missing confidence tags, dangling cross-refs, sources without page anchors).
- `/findings --footer <slug-or-heading>` — re-format only the Sources footer of one specified entry to the standardized 4-class schema (used to roll out the schema across an existing doc).
- `/findings --update <slug-or-heading> [--artifact <AN-id-or-build-path>]` — **surgical single-entry edit**. Update one finding's body (headline, magnitude, caveat, confidence tag) after a new analysis result. Reads only `CLAUDE.md`, `findings.md`, and the optional triggering artifact. `--artifact` accepts either an AN id (preferred — e.g. `AN-019`; the skill reads `docs/analyses/an-019-*.md` to recover script + target + headline) or a raw `build/<path>` (fallback for runs not yet ledgered). Does not re-derive other findings, does not re-read `stylized-facts.md`/briefs/audits. Use from `/next` step 5 when a run affects exactly one existing finding (re-run with revised magnitude, parser fix that shifts a number, confidence promotion/demotion after replication). Distinct from `--refresh` (which walks all findings) and `--footer` (which touches only the Sources block).

## Finding the workspace root

The workspace root contains `CLAUDE.md` alongside `projects/`, `pipelines/`, `ideas/`, `research/`. If the current directory is inside a project, search upward to find the root. Use `$ROOT` for all paths below. The project root is `$ROOT/projects/<slug>/` — use `$PROJ` for it.

## Locating the findings doc

Discovery order, first hit wins:

1. `$PROJ/docs/findings.md`
2. `$PROJ/docs/findings/index.md` (folder mode — see below)
3. `$PROJ/docs/reference/key-findings.md` (legacy)
4. Project-specific path declared in `$PROJ/CLAUDE.md` or `$PROJ/docs/summary.md`

If none exists, ask the user which location to create. Default suggestion is
`docs/findings.md`. Do not silently create the file at a non-canonical path.

## What to read (in order)

Read these files to build context. If one is missing, note it and move on; never invent its content.

1. `$PROJ/CLAUDE.md` — current focus, key terms, conventions
2. `$PROJ/docs/summary.md` — research question (required)
3. `$PROJ/docs/findings.md` (if exists) — existing entries; match their template exactly
4. `$PROJ/docs/reference/stylized-facts.md` (if exists) — fact-by-fact ledger; findings draws its empirical anchors from here
5. `$PROJ/docs/hypotheses.md` (if exists) — every empirical finding should map to at least one hypothesis or angle
6. `$PROJ/docs/briefs/*.md` — narrative synthesis files; cross-link from findings entries
7. `$PROJ/docs/audits/findings/*.{md,json}` (if exists) — output of `/findings-audit`; this contains anchor quotes and corroborations to fold into entries
8. `$PROJ/build/table/*` and `$PROJ/build/figure/*` — own-analysis artifacts; each load-bearing finding should cite at least one
9. `$PROJ/source/table/*.py` and `$PROJ/source/figure/*.py` — scripts producing the artifacts; cite the script in the Sources footer
10. `$PROJ/references/{cnj,pgfn,ipea,reports,…}/*.pdf` — aggregate reports; needed for `*Reports*` source-class citations with `#page=N` anchors
11. `$PROJ/references/news/stories.csv` and `$PROJ/references/news/texts/*.txt` — news anecdotes; needed for `*News anchors*` source-class citations with anchor quotes
12. `$PROJ/paper/main.tex` (if exists) — load-bearing findings should match what the paper presents; flag drift

## Document & entry format

Full spec — templates, verbatim confidence-tag scheme, entry schema, headline
rule with examples, Sources footer, path conventions, folder-mode details,
migration, and the validation badge — is in
[`reference/entry-format.md`](reference/entry-format.md). **Read it before
drafting, extending, or updating entries.** The essentials:

- **Default layout is folder mode**: `docs/findings/` with `index.md` (intro +
  confidence scheme + linked overview) and one `<slug>.md` per finding. Flat
  `docs/findings.md` is legacy — maintain existing ones, don't create new.
- **Each entry** = a confidence tag + a self-contained headline sentence (≤40
  words, one declarative claim about the world, with the load-bearing number(s)
  and AN cite(s)), then 1–4 paragraphs of anchored explanation, then a
  four-class **Sources footer** (*Own analysis* / *Reports* / *News anchors* /
  *Cross-refs*, plus *Validation* if the project has a ledger). Absent classes
  read `none direct`, never omitted.
- **Confidence tags** 🟢/🟡/🔴 mean replicated / single-source / provisional for
  empirical findings, and strong / plausible / speculative for interpretations.
- Findings **cite the AN ledger entry** (`AN-NNN`) and take the magnitude from
  the AN page — they don't re-derive numbers.

## Draft protocol

1. Read all inputs (see "What to read"). Build a **finding candidate list** from:
   - Existing entries (preserve as-is in normal/extend mode)
   - `build/table/*.csv` and `build/figure/*.pdf` artifacts not yet cited in any entry — each is a candidate finding
   - `docs/audits/findings/*.json` — anchor quotes and corroborations to fold in
   - The user's pointer if they specified one
2. Filter aggressively. Keep only findings that (a) are *load-bearing* for the paper or for an interpretation, (b) have at least one own-analysis artifact or anchored external source, (c) state a directional claim ("X is rare", "Y rises with Z"). Drop merely descriptive cuts unless they support a specific interpretation downstream.
3. For each finding, draft the entry per the schema:
   - Pick confidence tag honestly per the scheme.
   - Headline sentence carries the load-bearing number.
   - Expanded explanation grounds the number with anchored citations.
   - Sources footer in the four-class format with all four classes (use `none direct` if a class has no entries).
4. Aim for **20–50 entries** in mature projects, **5–15** in early-stage. More than 60 means insufficient curation — split into a separate page or move some to `stylized-facts.md`.
5. The `## Findings overview` index must include every entry with a one-line summary and an anchor link. This is the doc's table of contents and is critical for navigability.

## Update mode (`--update <slug-or-heading>`)

Surgical single-entry edit. Use when one finding's content changed
(magnitude revised, caveat added, confidence tag moved, parser-fix
walk-back) and the rest of `findings.md` should remain untouched.

**Minimal read set** — do not re-read the full briefing pack:

1. `$PROJ/CLAUDE.md` — for current focus and naming conventions.
2. `$PROJ/docs/findings.md` — to locate the target entry
   and respect its template exactly.
3. The `--artifact` argument (if given). If an AN id: read
   `$PROJ/docs/analyses/an-NNN-*.md` to recover the script, target,
   headline, and confidence — the AN page is canonical, do not
   re-derive numbers from the build artifact. If a `build/<path>`:
   read the artifact itself.
4. The triggering script's IAT docstring (via the `source/X.py →
   build/X.*` convention, or the `script:` field on the AN page) —
   for context.

Do **not** re-read `stylized-facts.md`, briefs, audits, or paper.tex
unless the target finding's Sources footer explicitly cites them and
the update would change those citations.

**What to edit:** only the target finding's entry. Preserve the
template (headline, expanded prose, Sources footer four-class schema).
Update only the fields affected — typically the magnitude in the
headline + the prose explanation, optionally the confidence tag.

**What not to touch:** other findings, the `## Findings overview`
table of contents (unless the headline changed materially), the
confidence-tag scheme section, or any cross-cutting structure.

**`@claim` registry:** if the entry uses `@claim` tokens, update the
token values rather than free-text edits where possible. That keeps
`--refresh` cycles cheap on subsequent re-runs.

**Output:** the edited `findings.md` plus a one-paragraph summary
(which entry, before → after, what artifact was cited). The summary
belongs in the `/next` end-of-iteration report.

Distinct from:
- `--refresh` (walks **all** findings, recomputes from artifacts,
  flags drift — for post-pipeline-rerun bulk verification).
- `--footer` (touches only the Sources footer schema, no body edits).
- `--extend` (appends new findings; doesn't edit existing ones).

## Refresh mode (`--refresh`)

This is the most valuable mode and the one most often skipped. After any pipeline rerun or parser fix:

1. For each entry, identify the load-bearing numbers in the headline and body. Patterns to look for: percentages, R$ amounts, counts, ratios.
2. Locate the underlying build artifact (typically the first `*Own analysis*` link in the Sources footer). Read it.
3. Compare current numbers to the entry's stated numbers. Flag any discrepancy >2pp on percentages or >5% on counts.
4. For each flagged entry, present:
   - The entry headline + stated number
   - The current build-artifact number
   - The likely source of drift (parser fix, new data, recompute)
   - A suggested edit (corrected number + a "refreshed YYYY-MM-DD" parenthetical)
5. Do not auto-edit. Show the user the diff and let them confirm each fix. Stale numbers are often the result of an earlier curated narrative the user wants to preserve while flagging drift.

This is the mode that catches problems like a "50% of payments are ghost" headline that was never updated after a parser fix moved 20% of cases to a different bucket.

## Audit mode (`--audit`)

Do not write. Check:

- Every entry has confidence tag, headline sentence, expanded explanation, Sources footer.
- Every Sources footer has all four classes (or explicit `none direct`).
- Every report citation has a `#page=N` anchor (not just stem+page in plain text).
- Every news citation links to a `texts/NNN.txt` file that exists.
- Every own-analysis artifact path resolves (file exists in `build/`).
- Every cross-ref anchor resolves (heading exists in the linked doc).
- Every interpretation entry has a Draws-on / Cross-refs paragraph naming at least one empirical finding it depends on.
- Every empirical finding tagged 🟢 names at least two independent samples or studies in the body.

Report findings as a bulleted list of gaps, grouped by entry. Do not auto-fix.

## Extend mode (`--extend`)

1. Preserve every existing entry verbatim.
2. Compute the diff between current `build/table/*` and the artifacts already cited across existing entries. Identify orphan artifacts (built but never cited) that look load-bearing.
3. For each orphan, propose a new entry headline + a one-line summary. Wait for user pick before drafting full entries.
4. Append new entries after the last existing one, marked with a `Status: drafted YYYY-MM-DD` line if the project's template uses status fields.

## Footer-only mode (`--footer <slug>`)

For migrating an existing doc into the standardized footer schema without touching the prose. Useful as a one-time roll-out tool.

1. Locate the entry by anchor slug or by phrase match in headlines.
2. Parse the existing Sources line (which may have been single-line or in a `Draws on:` form).
3. Re-format into the four-class structure. Auto-classify each existing reference:
   - Paths starting with `build/` → *Own analysis*
   - Paths starting with `references/` and matching `.pdf` → *Reports* (and add page anchor if a page is mentioned in body or stem)
   - Paths starting with `references/news/` or text matching news pattern → *News anchors*
   - Internal anchor links (`#...`) or cross-doc links → *Cross-refs*
4. Add `none direct` for any class that has no existing references.
5. Show the user the diff and confirm before writing.

## Interaction with `/findings-audit`

The two skills are complementary:

- `/findings` produces and maintains the doc.
- `/findings-audit` reads the doc and stress-tests its claims against external evidence (news, reports), producing a JSON+MD audit at `docs/audits/findings/YYYY-MM-DD-targeted.{md,json}`.

When `/findings-audit` finds a corroboration or weak counter-evidence, the audit JSON contains anchor quotes that should be folded back into the relevant `/findings` entries. The `--extend` mode of `/findings` should look for any audit JSON newer than the doc's last edit, and surface its corroborations as candidate new bullets in existing entries.

## Interaction with adjacent skills

- **`/hypothesis`**: every empirical finding tagged 🟢 or 🟡 should map to at least one hypothesis. The audit-mode check for "every interpretation has Draws-on cross-refs" is the symmetric check.
- **`/theory`**: interpretations in key-findings draw on theory.md frameworks. Cross-refs from interpretations to theory.md are encouraged.
- **`/literature`**: when a finding's headline number is being compared across studies (e.g., INSPER 16% vs IPEA 6.5% vs own 1.6%), the supporting studies should appear in literature.md. The Sources footer's `*Reports*` and `*News anchors*` classes are not a substitute for academic literature — they're the institutional and current-events parallel.
- **`/anecdotes`**: when a finding leans on news anecdotes, those rows must exist in `references/news/stories.csv` (populated by `/anecdotes`). Don't cite news that isn't in the curated corpus.

## Guardrails

- **Ground every number.** Every load-bearing number traces to a build artifact or a source linked in the Sources footer. If it's only from memory, drop it or run the analysis first.
- **Verify page numbers.** Check `#page=N` citations against the PDF (open it or grep its text); write `[CNJ-DEF24 — page tbd]` rather than guess. A report cite without a working page link just makes the reader hunt.
- **Anchor every quote.** News-anchor quotes are exact substrings of the linked `texts/NNN.txt` — a bare `[stories.csv #310]` tells the reader nothing. Paraphrases aren't anchor quotes.
- **Date every update.** Sub-paragraphs, footer changes, and confidence upgrades carry `(added YYYY-MM-DD)` / `(refreshed YYYY-MM-DD)`.
- **Preserve superseded numbers on refresh.** Write the new number first, then `*(refreshed YYYY-MM-DD; previously stated as X under <pre-fix universe>)*` — keeps the audit trail without burying the current value.
- **Refresh after pipeline changes.** Reruns and parser fixes drift build numbers away from the entry text; run `--refresh`, and don't carry a stale "fix moved X%→Y%" note once it no longer matches the data (move it to `done.md`).
- **Every claim is anchored.** A finding without anchored evidence is a hypothesis — move it to `hypotheses.md`. Every interpretation names its empirical premises in the Draws-on paragraph; one without them is op-ed.
- **Keep empirical and interpretation separate.** A descriptive cut ("X is 27% of cases") is empirical; the reading of it ("X is the modal channel") is the interpretation.
- **Keep the overview in sync.** Adding an entry means adding it to `## Findings overview`, or it's unreachable from the top of the page.
- **Honest confidence tags.** Don't push 🟡→🟢 because the paper needs it; upgrade only on real independent replication.

## Output protocol

1. **Populate/extend:** print a preview — entry count, new vs existing entries, count of placeholder `[ref needed]` or `[page tbd]` markers. Wait for confirmation unless the user said "go ahead." Write the file. Report the path and any unresolved placeholders.
2. **Refresh:** print a per-entry diff showing stated vs current numbers. Wait for confirmation per entry before applying. Refreshed entries get a parenthetical date stamp.
3. **Audit:** print a bulleted list of gaps. Suggest next mode (`--refresh` if numbers drifted, `--extend` if new artifacts orphaned, `/findings-audit` if external corroboration is the gap).
4. **Footer:** show the diff for the one entry; confirm; write.