Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: add ADR-0014 and provenance chain glossary entries

Browse Source 
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:
Defame1297
2026-06-27 09:09:43 +00:00
parent 562527dfc4
commit 8dc5241c1c
2 changed files with 38 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CONTEXT.md
View File

@@ -95,9 +95,15 @@ Field (`source:`) in a skill's `META.md` tracking upstream provenance. An array
<!-- ### META.md
A per-skill markdown file containing a single YAML code block with provenance and audit fields: `version`, `updated`, `when`, `source`, and `references`. Lives alongside the SKILL.md in the skill directory (either `.agents/skills/<name>/META.md` or `plugins/<plugin>/skills/<name>/META.md`). Not loaded at agent startup — progressive disclosure principle: name and description route the skill; provenance is only needed for upgrade reviews and audits. Prevents these fields from being scanned on every session start alongside every skill's name and description. The authoritative schema is `META-TEMPLATE.md` in `plugins/kyberforge/skills/write-skill/`. See also: [[Source field]]. -->
### 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-<slug>.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/<plugin>/docs/research/docs/<topic>/`; (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.

32
docs/adr/0014-skill-audit-info-finding-level.md Normal file
View 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.