Add canonical "evidence-based" source with a hierarchy of evidence confidence

[mxriverlynn]

Request

Add a canonical source for "evidence-based" — the term that runs through nearly every Han skill and agent — modeled after the existing YAGNI canonical pair (docs/yagni.md + plugin/references/yagni-rule.md). The new source should include a specified hierarchy of confidence for evidence. Examples given by the reporter:

• running code > documentation
• primary sources > secondary sources

Issue type

Feature request.

What is known from the report

• "Evidence-based" is a load-bearing concept across the plugin (YAGNI, planning, review, investigation, research) but has no single canonical definition the way YAGNI does.
• The reporter wants the same shape as YAGNI: a docs/ long-form doc plus a plugin/references/ rule file consumable by skills and agents.
• The doc must rank evidence by confidence. The reporter named two example tiers; more tiers are implied but not enumerated.

Open questions to resolve before this is plannable

• Full hierarchy. What are all the tiers, in order, and how do they compare against each other when two pieces of evidence are at different tiers? Reporter named two example pairs but did not specify the complete ladder.
• Tier definitions. What counts as "running code" (passing tests? observed in production? a reproduction in a REPL?); what counts as a "primary source" (codebase? user statement? official spec? maintainer's commit message?); same for documentation and secondary sources.
• Tie-breakers within a tier. When two pieces of evidence sit at the same tier (e.g. two different observed reproductions) and disagree, how do skills and agents decide.
• Scope of application. Whether this rule supersedes or complements the YAGNI evidence list, or sits as a separate cross-cutting concept that YAGNI references.
• Consumers. Which skills/agents should explicitly cite the new canonical source, and whether existing references to "evidence-based" need to be retrofitted with links.
• Failure mode when evidence is absent. What the skill/agent should do when no tier of evidence exists for a claim (defer, ask the user, mark Unknown, refuse to commit).
• Naming. What the canonical doc is called (docs/evidence-based.md? docs/evidence.md?) and the matching rule file under plugin/references/.

Suspected areas of impact

• New docs/evidence-based.md (long-form, mirrors docs/yagni.md).
• New plugin/references/evidence-rule.md (consumable rule, mirrors plugin/references/yagni-rule.md).
• Index updates in CLAUDE.md "Core mental model" section, alongside the YAGNI entry.
• Cross-references from docs/yagni.md and plugin/references/yagni-rule.md, which already use "evidence-based" without a canonical definition.
• Likely citations across planning, review, investigation, and research skills (plan-a-feature, plan-implementation, iterative-plan-review, code-review, architectural-analysis, investigate, research, gap-analysis) and their agents.

Severity / reproducibility

• Severity: Low (new canonical content, nothing broken).
• Reproducibility: N/A — feature request.

Recommended next step

Clarify the open questions above with the reporter, then run /plan-a-feature to specify the doc's structure and consumer integration before drafting content.