findings

Files (2)

• SKILL.md
• entry-format.md · reference/

SKILL.md (first lines)

# /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.

From hsigstad/research-kit, MIT.

More from hsigstad/research-kit