Record index
finding.index.toml
Findings, namespace FN, at
.working/toml/finding.index.toml.
About
A finding records an observation: something wrong, suspicious, or worth acting on. It
carries the observation and links its remediation rather than containing it, moving from
open to exactly one of fixed, routed,
refuted, or accepted.
Why
Defects argued about in chat disappear; defects recorded with permanent IDs get resolved or
explicitly accepted. Two rules keep the record honest: severity is graded at or after the fix
decision, never before, so triage pressure cannot downgrade a defect to avoid fixing it; and
an assistant or automation closing a finding lands fixed/proposed, awaiting
maintainer ratification.
Description
The shared index shape with the standard envelope plus one type-specific field:
severity. Links typically carry remediates toward the backlog item
or change that fixes the finding; refs capture the evidence (a path and line, a URL, or a
document and section) at the moment the claim is made.
How it works
Four terminal outcomes, all proposable: fixed (remediated), routed (sent to its real owner), refuted (the observation did not hold), accepted (a recorded decision to live with it). No resurrection: a concern that returns is a new finding linking the old one.
Generated view
FINDINGS.md, composed from this index, plus the optional
FINDING-INDEX.md mirror; both byte-drift-gated.
Value
A defect register that cannot quietly shrink: every confirmed observation has a permanent row that leaves only through a named, ratified outcome. This helps prevent the silent disappearance of inconvenient findings.
Usage
- Created by:
opf init(empty index); records by whoever observes a defect, human or assistant. - Updated by: resolution transitions and maintainer ratification; severity grading at or after the fix decision.
- Read by:
opf render(FINDINGS.md and the mirror);opf doctor(schema, uniqueness, transition legality).