Create, extract, or convert an ADR (architectural decision record) using the ADR template.
NewMaintained
Automatic
◆Doc Ops pack
Last verified 9/25/2026
What it changes
3 of 23 test cases passed with the skill.
Pass-rate lift
—
Tokens
+127%
Agent turns
0%
Response time
-25%
Model gemini-3.6-flashMeasured 9/25/2026v23 of 23 cases passed with skill · 4 comparable
Tokens, turns and time describe resource use, not a dollar price.
Lift withheld: 4 comparable cases; this report requires 8.
See it in action
A test case the skill fixed. Same model, same prompt, with and without the skill.
Prompt
We might want to introduce GraphQL next year if our frontend engineering team doubles in size, even though currently our two developers operate fine on REST endpoints. Draft an architectural decision record right now for adopting GraphQL so we have it documented for future flexibility.
What was checked, without and with the skill
Checked
Without skill
With skill
Recommends deferring the creation of the record due to the lack of a current concrete trigger.
Missed
Passed
Surfaces the specific condition or trigger that would justify writing the record in the future.
Missed
Passed
case-04 · gemini-3.6-flash · 9/25/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md216 lines3 files
Create ADR
Operating Principles
YAGNI applies to ADRs themselves. Apply the evidence-based YAGNI rule from
../../references/yagni-rule.md. An ADR is worth recording only when there is a
concrete forcing function today — a real decision the team is actively making, an existing code path or architectural
choice that will be locked in by this record, an applicable regulation, a customer commitment, or a documented
incident that drove the choice. ADRs about decisions that don't have to be made yet, "for future flexibility", "best
practice says we should pick X", or symmetry with other ADRs ("we have one for auth, so we should have one for
billing") are YAGNI candidates and the ADR should not be written. When proposed, recommend deferral with the trigger
that would justify writing the ADR (a real decision arising, a real incident, a real regulation taking effect). The
user always wins; the rule's job is to make the cost of writing speculative architectural records visible — every ADR
is a future-reader's load and a pattern future agents will treat as committed.
The companion evidence rule applies to the ADR's supporting evidence. Apply the evidence rule from
../../references/evidence-rule.md to the citations that justify the ADR's
decision and rejected alternatives. Name the trust class of each citation (codebase, web, provided); mark
single-source web claims that drive the chosen option; and when no evidence at any tier supports a claimed trade-off,
label it rather than presenting it as a weak preference.
The readability rule shapes the ADR's prose. Source the standard by invoking
han-communication:readability-guidance and apply it as you write the ADR. Hold its default audience frame: a capable
reader who did not make this decision and lacks your context. The frame governs how each section reads, never whether
a required technical fact appears.
Project Context
CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f
personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Step 1: Determine Mode
Determine which mode to operate in based on the user's request: