diff --git a/CONTEXT.md b/CONTEXT.md index 00ba9b3..56e8a29 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -95,9 +95,15 @@ Field (`source:`) in a skill's `META.md` tracking upstream provenance. An array +### INFO (finding level) +A third finding level in `skill-audit` reports, below SUGGESTION. Observational — flags something worth noting that is not actionable and does not imply a defect. A skill with only INFO findings is a clean PASS. Counted separately in the result block as `· P info` and never mixed into the FAIL or SUGGESTION counts. Current use: a `references/*.md` file with no `source_keys` when `sources.md` is present; a skill-level source slug not found in the upstream research sources. See ADR-0014. + ### Provider-agnostic issue tracker Skills and workflows reference "linked issue" generically rather than a specific provider. In the file-based phase, an issue is a `docs/issues/NNNN-.md` file. When Gitea MCP is configured, the same skills use it instead. The active backend is determined at runtime by MCP availability. "Issue" is the canonical cross-provider term (GitHub, GitLab, Gitea all use it). +### Provenance chain +The three-stage traceability record linking a skill back to its research inputs: (1) `/research` produces topic docs and a `sources.md` in `plugins//docs/research/docs//`; (2) `/skill-author` reads those docs and records which sources informed which skill files in `references/sources.md` (including a `Research doc:` back-pointer to the upstream research file) and `source_keys` frontmatter on `SKILL.md` and `references/*.md`; (3) `skill-audit` validates the chain is complete and internally consistent via `validate-provenance.sh`. A skill with research input but no `references/sources.md`, or with `source_keys` that don't match `references/sources.md` slugs, has a broken provenance chain. + ### PRD scope A PRD contains: problem statement, goals, explicit non-goals, functional requirements at feature level, success criteria. Never contains: technical approach, implementation steps, or EARS-level detail. HOW is handled downstream: workstream-level technical approach belongs in `architecture-review` (≥2 options, tradeoffs, optional step after `write-prd`); issue-level HOW belongs in issue design notes. Prerequisite: a completed grill session. Validated by inline self-checks in the `write-prd` skill. diff --git a/docs/adr/0014-skill-audit-info-finding-level.md b/docs/adr/0014-skill-audit-info-finding-level.md new file mode 100644 index 0000000..23cf925 --- /dev/null +++ b/docs/adr/0014-skill-audit-info-finding-level.md @@ -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.