docs: add ADR-0014 and provenance chain glossary entries
Record the decision to add INFO as a third skill-audit finding level (observational, non-actionable, does not affect pass/fail). Add Provenance chain and INFO (finding level) to CONTEXT.md glossary. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
32
docs/adr/0014-skill-audit-info-finding-level.md
Normal file
32
docs/adr/0014-skill-audit-info-finding-level.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# Add INFO as a third finding level in skill-audit reports
|
||||
|
||||
`skill-audit` shipped with two finding levels: FAIL (blocks shipping) and
|
||||
SUGGESTION (optional improvement). Provenance validation introduced observations
|
||||
that are worth surfacing but not actionable: a `references/*.md` file with no
|
||||
`source_keys` when `sources.md` is present, and a skill-level source slug absent
|
||||
from upstream research docs. Folding these into SUGGESTION would imply they
|
||||
should be fixed — but retroactive source backfill after a reference file is
|
||||
written is unreliable and not expected practice. A third level, INFO, is therefore
|
||||
introduced: observational, no action implied, never changes the pass/fail verdict.
|
||||
Counted separately in the result block as `· P info`.
|
||||
|
||||
## Considered options
|
||||
|
||||
**SUGGESTION with softer language (rejected)** — describe the finding as "worth
|
||||
noting" rather than "should be fixed." Rejected because SUGGESTION already carries
|
||||
an established meaning in the report; softening the language creates ambiguity
|
||||
without changing the semantic level. Downstream consumers (humans, skill-improve)
|
||||
would need to infer intent from prose rather than a stable token.
|
||||
|
||||
**Suppress entirely (rejected)** — omit findings that have no fix. Rejected
|
||||
because the observations are useful for a human reviewing provenance completeness.
|
||||
Silent omission loses information without reducing noise.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Report format gains a third token: FAIL, SUGGESTION, INFO. INFO findings do not
|
||||
affect pass/fail; counted as `· P info` in the result block.
|
||||
- `skill-improve` currently ignores anything below FAIL — that behavior remains
|
||||
correct; INFO findings are not forwarded to it.
|
||||
- Future soft observations should use INFO rather than SUGGESTION when no fix is
|
||||
actionable.
|
||||
Reference in New Issue
Block a user