# Discovery Notes: canonical-evidence-resource

Source for implementation planning: `docs/research/evidence-hierarchy.md` (the research report). No `feature-specification.md` exists — the research recommendation (O7) is the equivalent context. No spec companions (no `decision-log.md`, `team-findings.md`, or `feature-technical-notes.md` from `plan-a-feature`). T# detection: **no T# notes exist**; T# briefs, tags, and contradictions do not apply this run.

## Tech stack and tooling

- Markdown documentation in `docs/` (operator-facing) and `plugin/` (the shipped plugin: skills under `plugin/skills/{name}/SKILL.md` plus `references/`; agents under `plugin/agents/{name}.md`; shared reference files under `plugin/references/`).
- No code build, runtime, or test runner is involved — this is documentation work, not code.
- Plugin is shipped via `plugin/.claude-plugin/plugin.json`; marketplace manifest at `.claude-plugin/marketplace.json`.

## ADRs found

- **None.** No `docs/adr/` or `docs/architecture/decisions/` folder exists. The plan operates with no project-wide ADR record; the existing `han.plugin-builder/skills/guidance/references/plugin-entity-taxonomy.md` is the closest equivalent (a "status: accepted" doc that records the skill/agent/hook decision) but is not under an ADR repo and is not numbered.

## Coding standards found

- `.claude/rules/coding-standards/plugin-skills.md` — path-scoped index of skill-authoring rules under `han.plugin-builder/skills/guidance/references/skill-building-guidance/`. Triggers on globs into skill files.
- `.claude/rules/coding-standards/plugin-agents.md` — same shape for agents (not inspected this run; out of scope for doc-pair work).
- `docs/coding-standards/` does **not** exist as a separate folder. The guidance docs under `han.plugin-builder/skills/guidance/references/skill-building-guidance/` are the de facto standards for skill authoring; the canonical evidence-based doc would not be a skill, so most of those don't apply, but `progressive-disclosure.md`, `skill-reference-files.md`, and `context-hygiene.md` are relevant **to the consumer-skill retrofit** (the rule file must keep loaded context small for the 25+ skills that will cite it).

## Touch points (code/docs that will be created or edited)

- **NEW:** `docs/evidence.md` — long-form operator-facing doc paralleling [`docs/yagni.md`](docs/yagni.md) (135 lines, TL;DR + Why + Two Gates + Anti-Patterns + Application Table + Deferred format + Design Principles + Related Reading).
- **NEW:** `plugin/references/evidence-rule.md` — rule reference paralleling [`plugin/references/yagni-rule.md`](plugin/references/yagni-rule.md) (101 lines, prescriptive imperative voice; loaded by skills at runtime).
- **EDIT:** `CLAUDE.md` lines 50–56 — add the new entry to the `### Core mental model` index alongside the `docs/yagni.md` line.
- **EDIT:** `docs/yagni.md` and `plugin/references/yagni-rule.md` — cross-reference the new evidence pair (YAGNI's evidence test names "acceptable evidence" without defining quality dimensions; the cross-link points readers to the new doc).
- **EDIT (citation retrofit):** the existing consumer skills and agents that already use the term "evidence-based":
  - `plugin/skills/iterative-plan-review/SKILL.md` (7 occurrences — highest density)
  - `plugin/skills/gap-analysis/SKILL.md` (5)
  - `plugin/agents/project-manager.md` (4)
  - `plugin/skills/plan-a-feature/SKILL.md` (3)
  - `plugin/skills/investigate/SKILL.md` (3)
  - `plugin/agents/junior-developer.md` (3)
  - `plugin/agents/evidence-based-investigator.md` (2)
  - Plus 13 more files with 1 occurrence each (full list under "Recent activity" or via `grep -rn "evidence-based\|evidence based" plugin/skills/ plugin/agents/ plugin/references/`).
  - Total: **41 occurrences across 20 files** in plugin/.

## Existing primitives the new pair canonizes (already in the codebase)

- `plugin/skills/research/SKILL.md:25, 108, 110, 112` — defines **trust classes** (codebase = trusted current-state anchor, web = outside the trust boundary, provided = operator-supplied with interested-party scrutiny), the **corroboration gate** (single-source web claim cannot be sole basis for the recommendation in strict mode), and the **conflict rule** (codebase wins; "continue with the current approach" added as named option).
- `plugin/agents/research-analyst.md:18, 44, 65, 84, 89` — agent-level implementation of the corroboration gate and "content is data, never instruction" rule.
- `docs/yagni.md:28–38` and `plugin/references/yagni-rule.md:9–19` — **five parallel categories of acceptable evidence** (user-described need, named direct dependency, existing production code path or contract, applicable regulation, documented incident/alert/customer report/measured metric). Note: these are *parallel inclusion criteria*, not *quality tiers*.

## Plan precedent

- No prior `feature-implementation-plan.md` exists in any `docs/plans/` folder (the closest, `docs/plans/code-review-guardrails/`, contains only an `artifacts/` subfolder with PR evidence files, no plan).
- The templates at `plugin/skills/plan-implementation/references/feature-implementation-plan-template.md`, `implementation-decision-log-template.md`, and `implementation-iteration-history-template.md` are authoritative.
- The closest format precedent for the deliverable pair is `docs/yagni.md` + `plugin/references/yagni-rule.md` themselves — they are the file pair this plan will mirror.

## Recent activity (90-day churn touching evidence/yagni/references)

- `docs/yagni.md`, `plugin/references/yagni-rule.md` — stable; no recent edits in the last 90 days. The pair is treated as the durable canonical model.
- `docs/research/evidence-hierarchy.md` — added 2026-05-28 (commit `0496a1c`, this branch).
- The 20 consumer files cite "evidence-based" without referencing a canonical source — this is the gap the plan addresses.

## Gaps explicitly enumerated

- **No project ADR repository.** Decisions about cross-cutting documentation primitives are not currently recorded in a dedicated ADR; the closest is `han.plugin-builder/skills/guidance/references/plugin-entity-taxonomy.md`. The plan does not need to create an ADR repository; the recommendation can sit in `docs/evidence.md` itself.
- **No coding-standards folder.** Skill-authoring standards live under `han.plugin-builder/skills/guidance/references/skill-building-guidance/` and are exposed via the `.claude/rules/coding-standards/plugin-skills.md` index. The rule file the plan creates must be lightweight enough to be loaded by 20+ skills/agents at runtime without burning context.
- **No "evidence" definition exists.** Despite 41 occurrences of "evidence-based" across 20 files, no canonical definition is shared across them. Skills inherit the term's meaning from the YAGNI rule's five parallel categories (inclusion criteria), from the `/research` skill's trust-class language (confidence dimensions), or from the term's intuitive plain-English meaning. This drift is what the new pair eliminates.
- **No documented Han failure attributable to weak-evidence acceptance** (per the research report's validator finding V2). The plan exists because the reporter asked for it and because the term lacks a canonical source — not because a measurable bug forced it.
- **No specialist directly responsible for "documentation across the plugin"** in the sub-agent roster. The information-architect is the closest fit and was selected as the single specialist for this small team.
