spec-drift-sync
Use before merging any non-trivial change. Reconciles code with specs, and code/specs with memories, runbooks, and telemetry docs (Spec Drift Synchronization).
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- spec-drift-sync
- description
- Use before merging any non-trivial change. Reconciles code with specs, and code/specs with memories, runbooks, and telemetry docs (Spec Drift Synchronization).
03 SKILL.md 正文
spec-drift-sync
Prerequisites
- The branch diff (
git diff main...HEAD).
Workflow
- List what changed in behavior or contracts: a package's public API, signing or key-handling behavior, the Snapshot or Play client handling, error types, contract copies, what the Wrapper emits, build or release tooling.
- For each, find its canonical doc (see the table in
AGENTS.md#knowledge-maintenance)
and compare:
- code changed behavior → update the spec;
- spec changed → the code must implement it (or the spec change is reverted);
- contract changed → vectors and tests updated.
- Contract copies: every file in the
contractspackage matches its entry in the lock file (source commit and hash); generated types match a fresh regeneration; released vector files are untouched; the package holds no logic and only tests import its test-only entry. - Public API: exported names,
package.jsonexports, the changeset, and the package'sREADME.md(public documentation: role, status, entry points, guarantees, and no contributor material) agree with the spec. - Security: nothing in the diff logs, stores, or exposes a key or token; the spec's statement of what may never be logged still holds.
- Telemetry: anything that logs, emits metrics, or sends events is described in its spec, with what it may never contain.
- Memories: update
last-verifiedon memories you re-checked; fix stale ones. - Resolve working memories linked to the branch.
- Added or resolved a
TODOmarker → check it is still accurate (git grep -n "TODO"). - Added, renamed, moved, or split a spec section → the table of contents in
specs/README.mdmatches the headings, a long contract section lives in its own file as the conventions there say, and no "above" or "below" points across files. - Report what was synchronized, or state "no drift" with the evidence.
Constraints
- Follow the precedence order; if code and spec disagree and the intended behavior is unclear, ask the human with ask-the-human (options: fix the code, fix the spec, or open an RFC) — do not guess.
Useful commands
git diff --stat main...HEAD
git grep -n "TODO"
pnpm check
Expected output
A drift report plus the doc/code changes in the same PR.
References
04 同仓库更多 Skills
<skill-name>
Use when <situation>. One or two sentences.
write-tests
Use when adding or changing behavior, signing code, contracts, or the UI. Chooses the right test level and applies the repository's test rules.
shepherd-a-pull-request
Use when reviewing a pull request on GitHub, following up on a review after new pushes, or answering review comments on your own pull request. The `gh` procedure behind the pr-shepherd agent, with draft-then-confirm posting.
prd-to-spec
Use when given a rough PRD, feature request, or raw requirement. Turns it into a spec update, an RFC when the change is significant or contested, and an ADR for hard-to-reverse decisions.
ask-the-human
Use when you hit an open question, a decision that is not yours to make, a gap or ambiguity in a spec, or a draft that needs a human's confirmation. Asks through the host's structured-question tool with concrete options and a recommendation, instead of guessing or burying the question in prose.
add-a-package
Use when adding a new package under packages/ (or an app under apps/). Covers the placement check, the dependency direction, public API, wiring, tests, and docs.