文件监护人

文档 社区

技能解读

当前原文的自动摘译,尚未人工审校。

激活触发器(此存储库的架构)

当您在计划或正在进行的更改中观察到其中任何一个时,请激活: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.yml GHA 机器人完成。

超出范围(故意)

技能范围仍然很窄。它不会: 在对话中提及“bug”或“想法”时触发。提交 GitHub 问题是一种故意的用户行为,而不是文档事件。运行gh issue create或管理标签。警察在docs/和ADR检查之外未提交工作树状态。验证 GitHub 上问题正文中的交叉链接。

文档位置

在建议信息应该存在的位置时,请使用以下目标: 目标 · 目的 docs/adr/NNNN-*.md · 架构决策:技术选择、构建门变更、公共 API 表面、模块边界、发布流程变更 ARCHITECTURE.md · 模块映射、生命周期、数据流 — 描述性、源自代码 docs/CONFIGURATION.md · 面向用户的卡配置参考(每个新选项也必须放在这里)

选通测试——提议前申请

上述激活触发器是检测信号,而不是自动建议。触发器触发后,通过限制性“与”三过滤器来控制提案:难以逆转 - 稍后更改决策的成本是有意义的。在没有上下文的情况下令人惊讶——未来的读者在查看代码时会想知道“他们到底为什么这样做?”真正权衡的结果——有真正的替代方案,而你出于特定原因选择了一个。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
文档
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
WSL
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# 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 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。