assess-findings

Assess Findings Writer

The report-writing half of /assess. The deterministic core has written .assess/run-context.json (the data bus) and the assess-layer-scorer agent has returned the 0-8 scorecard. Your job is to assemble .assess/assess-report.md: the scorecard, the snapshots, the verbatim cross-layer findings, the lying signals, and the Top 3 Actions.

The deterministic parts are not yours to invent - you paste them. You write the prose around a findings section you cannot omit or reorder. This is the deterministic-core-writes-data / LLM-writes-prose split that makes the report reproducible regardless of which model drives the run.

Inputs

• $REPO_ROOT/.assess/run-context.json - the data bus (findings, attention, keyhole summary, prescribed actions, stats, diff).
• The scorecard returned by the assess-layer-scorer agent (the 0-8 score, per-layer verdicts, maturity label).

Read the cross-layer findings first

The layers above each measure one axis. The deterministic core also crosses those axes against each other and emits ten named findings - the "where to look" signals no single layer surfaces. Read them once, after the per-layer scans:

jq '.derived_findings, .attention, .keyhole_summary, .prescribed_actions' "$REPO_ROOT/.assess/run-context.json"

derived_findings is a fixed-order list of ten {name, paths, action} objects - all ten always present, paths may be empty. Omit a finding from the report when its paths is empty. Each pairs an axis-crossing with the action it implies:

• hidden_coupling - modular statically but bleeds across boundaries historically (files that keep changing together). The static map says "isolated"; git says "coupled." Action: investigate the seam before trusting the boundary.
• lying_map - high complexity under a stale doc: the map exists but no longer matches the territory. Staleness is the decaying-map churn ratio for a hand-written doc, but for a generated doc that declares provenance (frontmatter source: or a [[generated]] config mapping) it is measured against the source - the doc is stale only when its source is newer than it, so an accurate generated doc is never flagged. Action: fix or delete the doc - a wrong map is worse than none.
• unexplained_complexity - high complexity with no doc and no recorded intent. Action: write the missing contract. Do not auto-generate it - a guessed contract is just another lying map.
• untrusted_hotspot (E1 trust axis) - a complexity hotspot whose tests are hollow: an opt-in mutation pass let a high fraction of mutants survive, so the suite runs the code but doesn't pin it. Silent without mutation data (the default read-only run never fires it). Action: strengthen tests to pin observable behaviour, not internal state.
• self_referential_tests (E2 trust axis) - the code and its co-located tests were introduced in the same commit, so the suite may verify the author's mental model rather than independently-specified behaviour. Action: request human review - the tests verify internal consistency, not truth.
• unactioned_intent (write-side tendency) - files carrying stale promissory markers (TODO / FIXME / "remove after migration") that survived many edits to their own file without being kept: a lying map of intent. Silent when the marker scan is unavailable or the history is too thin to age markers. Action: action the promise - fix it, ticket it, or delete the marker/skip.
• accretion_ratchet (write-side tendency) - a top-band hotspot whose line count only ever ratcheted upward: monotonic net growth across multiple commits with almost no deletion pressure (deletions below ~15% of total churn). The fingerprint of a file appended to rather than reworked. Only surfaced for files already in the top complexity/size band, so a growing-but-simple file is never flagged. Silent when the scan is unavailable, and disclaimed (not dropped) when the git history is degenerate (shallow clone or squashed import). Action: refactor down - extract, delete dead code, or split the file.
• orphaned_understanding - high complexity with no human anchor and no intent: nobody owns the knowledge. Action: assign a human anchor before further change.
• candidate_dead_weight - high complexity with no runtime evidence it is live. The bias is to keep (static reachability can't see external callers - Layer 1's caveat applies). Action: verify liveness, then delete only if confirmed dead.
• refactor_boundary (positive) - high containment: edits stay local. A safe zone, never an attention row. Action: safe to hand an agent in isolation; cite these paths in Strengths.