assess-findings
Renders the /assess report from the deterministic run-context.json and the layer scorecard - the scorecard, the verbatim cross-layer findings, lying signals, and the mandatory Top 3 Actions. TRIGGER when the /assess orchestrator reaches the report-writing step; not a standalone user command.
bjcoombs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add bjcoombs/ai-native-toolkit --skill assess-findingsAbout this skill
name: assess-findings description: Renders the /assess report from the deterministic run-context.json and the layer scorecard - the scorecard, the verbatim cross-layer findings, lying signals, and the mandatory Top 3 Actions. TRIGGER when the /assess orchestrator reaches the report-writing step; not a standalone user command.
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-scoreragent (the 0-8 score, per-layer verdicts, maturity label), with itsevidencelist already re-checked bylib/evidence_check.py: only entries that held on disk remain there; the rejected ones arrive separately underevidence_rejected, each with thereasonthe check gave.
Existence and wiring claims cite only verified evidence. A report sentence saying a file or directory exists or is missing, or that something is or is not wired in (a workflow runs the linter, no CI job calls the script), must rest on an entry in the scorecard's evidence list and name the path that entry cites. When no verified entry backs such a claim, leave it out rather than restating it from the scorer's prose. The scorecard's per-layer Evidence cell is exempt only in its two empty states (no entries offered, every entry rejected), set beside the scorecard table below; a cell whose layer kept some verified entries cites only those, as the partial state there says. The deterministic findings you paste verbatim are already grounded and need no entry.
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, .attention_low_signal, .keyhole_summary, .prescribed_actions, .gap_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 (frontmattersource: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 at leaststale_touches_thresholdedits to their own file without being kept: a lying map of intent. A justified suppression (eslint-disable-line x -- reason,# noqa: X # reason) is never stale; a marker citing an issue or a date still ages. 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 ap