文件监护人
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- WSL
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Documentation Guardian
Keeps `docs/adr/` in sync with the code. Two jobs:
1. **Detect ADR-worthy changes** as they happen and propose drafting an ADR.
2. **Check planned and in-progress changes against existing ADRs** before they land.
The ADR conventions referenced here live in [`docs/adr/README.md`](../../../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:
1. **Hard to reverse** — the cost of changing the decision later is meaningful.
2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
3. **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`](../../../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
1. **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.
2. 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`.
3. Verify the planned change does not contradict any of them.
4. 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
1. Note any significant undocumented decisions made during the change.
2. Suggest an ADR for each, naming the file path.
## ADR mechanics
### Required structure
Mirrors [`docs/adr/template.md`](../../../docs/adr/template.md):
```markdown
# 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.
---
> Source: [chriguschneider/weather-station-card](https://github.com/chriguschneider/weather-station-card) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
激活触发器(此存储库的架构)
跳过 — 不触发
超出范围(故意)
文档位置
选通测试——提议前申请
文件/命令 -> docs/adr/ · docs/adr/README.md · src/chart/plugins/ · src/chart/plugins.ts · src/data-source/ · forecast.style · .github/workflows/ · Required status checks
内容校验值 -> 05a71f2824fe
当前原文的自动摘译,尚未人工审校。
激活触发器(此存储库的架构)
当您在计划或正在进行的更改中观察到其中任何一个时,请激活:
src/chart/plugins/下的新图表插件,或在src/chart/plugins.ts中注册的新条目。src/data-source/下的新数据源,或添加到阳光源解析链中的新层(现有层由公认的 ADR 管理 - 重新阅读docs/adr/以查找哪个层)。新的渲染模式或布局(除组合/站点/预测之外的第四个顶级模式),或超越 style1/style2 的新forecast.style变体。跳过 — 不触发
不更改合同的错误修复(没有新的公共选项,没有新的模块边界,没有新的依赖项)。在现有模块内进行重构,以保持公共表面相同。向现有代码添加测试覆盖率(包括
teardown-registry.ts上的 v1.5 #10 工作)。样式修复、lint 警告清理、已经严格的文件内的类型缩小。 E2E 基线再生由update-baselines.ymlGHA 机器人完成。超出范围(故意)
技能范围仍然很窄。它不会: 在对话中提及“bug”或“想法”时触发。提交 GitHub 问题是一种故意的用户行为,而不是文档事件。运行
gh issue create或管理标签。警察在docs/和ADR检查之外未提交工作树状态。验证 GitHub 上问题正文中的交叉链接。文档位置
在建议信息应该存在的位置时,请使用以下目标: 目标 · 目的
docs/adr/NNNN-*.md· 架构决策:技术选择、构建门变更、公共 API 表面、模块边界、发布流程变更ARCHITECTURE.md· 模块映射、生命周期、数据流 — 描述性、源自代码docs/CONFIGURATION.md· 面向用户的卡配置参考(每个新选项也必须放在这里)选通测试——提议前申请
上述激活触发器是检测信号,而不是自动建议。触发器触发后,通过限制性“与”三过滤器来控制提案:难以逆转 - 稍后更改决策的成本是有意义的。在没有上下文的情况下令人惊讶——未来的读者在查看代码时会想知道“他们到底为什么这样做?”真正权衡的结果——有真正的替代方案,而你出于特定原因选择了一个。