47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
---
|
|
name: agent-docs-repo-alignment
|
|
description: Use when checking whether AGENTS.md and agent-docs still match repository facts such as scripts, ports, directory structure, contract ownership, runtime behavior, or verification commands.
|
|
---
|
|
|
|
# Agent Docs Repo Alignment
|
|
|
|
## Overview
|
|
|
|
Use this skill to compare AGENTS and `agent-docs` against the real repository. It detects drift between documentation and code, config, scripts, tests, and folder structure.
|
|
|
|
## When to Use
|
|
|
|
- The user asks whether docs still match the repository
|
|
- A doc mentions commands, ports, packages, stack choices, routes, DTO ownership, or runtime behavior
|
|
- A previous audit found wording that might be stale
|
|
- A refactor changed scripts or layout and the docs may need follow-up updates
|
|
|
|
## Workflow
|
|
|
|
1. Read the docs in scope.
|
|
2. Read `../agent-docs/references/repo-alignment-checklist.md`.
|
|
3. Read `../agent-docs/references/severity-model.md`.
|
|
4. Read `../agent-docs/references/report-format.md`.
|
|
5. Inspect the repository facts relevant to the claim:
|
|
- scripts and `package.json`
|
|
- ports and proxy config
|
|
- directory and package structure
|
|
- shared contracts and DTO ownership
|
|
- tests or verification commands
|
|
- runtime and thread-sync code paths when relevant
|
|
6. Record observed facts first.
|
|
7. Compare doc claims against repo facts.
|
|
8. For each finding or confirmation, report it in this order:
|
|
- doc claim
|
|
- observed repo fact
|
|
- result: `confirmed` / `must-fix drift` / `wording drift`
|
|
- severity when the item is not `confirmed`
|
|
9. Use the repo-alignment shape from `report-format.md`.
|
|
10. Keep `must-fix drift` for statements that currently misstate repository facts, commands, ownership, or behavior. Use `wording drift` for stale or imprecise wording that should still be cleaned up.
|
|
|
|
## Boundary
|
|
|
|
- This skill checks docs against repo facts.
|
|
- It does not replace structural graph checks from `agent-docs-consistency`.
|
|
- It does not perform the actual doc rewrite; use `agent-docs-refactor` for that.
|