| name | documentation-guardian |
| description | Proactively suggests ADRs when architectural changes happen in this Lovelace card repo, and checks code changes against existing decisions in docs/adr/. Activate on new chart plugin, new data source, new render mode, new top-level config option, build/quality gate change, bundler or major-dependency bump, module-boundary break, or pattern deviation from an existing ADR. |
Documentation Guardian
Keeps docs/adr/ in sync with the code. Two jobs:
- Detect ADR-worthy changes as they happen and propose drafting an ADR.
- Check planned and in-progress changes against existing ADRs before they land.
The ADR conventions referenced here live in docs/adr/README.md. When the two disagree, docs/adr/README.md wins — update this skill to match.
Activation triggers (this repo's architecture)
Activate when you observe any of these in a planned or in-progress change:
- A new chart plugin under
src/chart/plugins/, or a new entry registered in src/chart/plugins.ts.
- A new data source under
src/data-source/, or a new tier added to the sunshine-source resolution chain (existing tiers are governed by an accepted ADR — re-read docs/adr/ to find which).
- A new render mode or layout (a fourth top-level mode beside Combination / Station / Forecast), or a new
forecast.style variant beyond style1/style2.
- A new top-level card-config option that the user can set in their YAML — these become public API and are notoriously hard to remove.
- A build / quality gate change: ESLint rule promoted warn→error, vitest coverage threshold moved, dependency-cruiser rule added or relaxed, new CI workflow under
.github/workflows/, change to the Required status checks set on master.
- A bundler or major-dependency bump: Rollup, vitest, lit, chart.js, playwright, eslint majors. The decision to take a major and the migration shape is ADR-worthy; patch/minor bumps are not.
- A boundary break: a new uplevel
import in src/chart/, src/editor/, or src/utils/. Either it needs to be removed, or the boundary itself needs an ADR change.
- A change to the e2e baseline regeneration flow (the
update-baselines.yml workflow, the playwright tolerance, the WSL fallback policy — pinning is governed by an accepted ADR; re-read docs/adr/ before changing the flow).
- A release-flow change — the steps listed in
CLAUDE.md for cutting vX.Y.Z.
- A pattern deviation from an accepted ADR — code that contradicts an existing decision.
Skip — do not trigger on
- Bug fixes that don't change a contract (no new public option, no new module-boundary, no new dependency).
- Refactors within an existing module that keep the public surface identical.
- Adding test coverage to existing code (including v1.5 #10 work on
teardown-registry.ts).
- Style fixes, lint-warning cleanup, type-narrowing inside an already-strict file.
- E2E baseline regenerations done by the
update-baselines.yml GHA bot.
- Single-file documentation edits (typo, link, prose tweak) that do not change a convention.
- Patch/minor dependency bumps via Dependabot.
- Lovelace dashboard / Bubble Card / user-side YAML examples in docs (those describe usage, not internal architecture).
Out of scope (deliberately)
The skill stays narrow. It does not:
- Fire on conversational mentions of "bug" or "idea". Filing a GitHub issue is a deliberate user act, not a documentation event.
- Run
gh issue create or manage labels.
- Police uncommitted working-tree state outside
docs/ and the ADR check.
- Verify cross-links in issue bodies on GitHub.
Documentation locations
When suggesting where information should live, use these targets:
| Target | Purpose |
|---|
docs/adr/NNNN-*.md | Architecture decisions: tech choice, build-gate change, public-API surface, module-boundary, release-flow change |
ARCHITECTURE.md | Module map, lifecycle, data flow — descriptive, derived from code |
docs/CONFIGURATION.md | User-facing card config reference (every new option must land here too) |
docs/CONDITIONS.md, docs/SENSORS.md, docs/TROUBLESHOOTING.md | User reference docs by domain |
docs/STYLE-GUIDE.md | Documentation conventions themselves |
CHANGELOG.md | Release-by-release log (every user-visible change is mentioned here) |
CLAUDE.md | Local-only context (gitignored). Do not propose ADR rationale to live here. |
Gating test — apply before proposing
The activation triggers above are detection signals, not auto-suggestions. After a trigger fires, gate the proposal by the restrictive AND-of-three filter:
- Hard to reverse — the cost of changing the decision later is meaningful.
- Surprising without context — a future reader will look at the code and wonder "why on earth did they do it this way?"
- Result of a real trade-off — there were genuine alternatives and you picked one for specific reasons.
All three must be true. If any one is missing, skip the ADR — the rationale belongs in a commit message, a code comment, the CHANGELOG.md, or simply in the diff itself.
- Easy to reverse → just reverse it later.
- Not surprising → nobody will wonder why.
- No real alternative → "we did the obvious thing" isn't worth recording.
This filter mirrors the one in the user-level grill-with-docs skill, so both stay aligned on what counts as ADR-worthy.
Proactive prompting
When a trigger fires and the AND-of-three gate passes, surface it before implementation, not after:
This change introduces / modifies / adds X. That's a deliberate architectural choice with genuine alternatives and meaningful reversal cost — should I draft an ADR for it before continuing?
Suggested: docs/adr/NNNN-descriptive-title.md.
If the user agrees, draft the ADR using docs/adr/template.md in the same PR as the code change. If the user defers ("not now, later"), respect that — do not nag in the same session.
For architecture suggestions in general (per CLAUDE.md): list pros/cons, then a recommendation, then act only after OK.
Compliance check
Before implementation
- List
docs/adr/ fresh — never assume a snapshot of the in-force set; new ADRs land regularly and a hardcoded list in this skill would silently drift.
- Read each accepted ADR whose title or
Decision section overlaps the staged paths or the planned change's surface area. Skip template.md and README.md.
- Verify the planned change does not contradict any of them.
- If the planned change contradicts an accepted ADR, raise it explicitly:
This approach differs from ADR 000N (<title>) which decided X. Two options: (a) adjust the implementation to match the ADR, (b) write a superseding ADR. Which one?
After implementation
- Note any significant undocumented decisions made during the change.
- Suggest an ADR for each, naming the file path.
ADR mechanics
Required structure
Mirrors docs/adr/template.md:
# NNNN: Title
**Status:** Proposed | Accepted | Deprecated | Superseded by NNNN
**Date:** YYYY-MM-DD
## Context
## Decision
## Consequences
- Pros / Cons / Tradeoffs
## Related
Numbering
- Sequential four-digit numbers: 0001, 0002, …
- Find the current highest number with
ls docs/adr/.
- Never reuse a number, even for deprecated or superseded ADRs.
Superseding
When a new decision overrides an old one:
- The old ADR's status becomes
Superseded by NNNN.
- The old ADR file is not deleted — history is preserved.
- The new ADR's status is
Accepted and its Related section links back to the superseded one.
Behavioural guidelines
- Lightweight, not bureaucratic. Suggest ADRs only when the change is genuinely a decision, not when the answer is obvious from the code or already documented.
- "Should I draft an ADR?" pattern, not auto-generation. Wait for a yes.
- Respect deferrals. If the user says "later" or "no", drop it.
- Pro/contra first. When recommending an architecture or tool choice, list alternatives, then a recommendation, then wait for OK before implementing.
- Connect the dots. Link new ADRs to related ones; reference the ADR from the relevant code section in
ARCHITECTURE.md or the corresponding user doc.
- English only in any file written to disk. Conversation can stay German.
