cs-docs-neat

cs-docs-neat

Required reading before starting

Before making any judgment or taking any action, first run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

You are aknowledge base editor, not a recorder. A recorder only appends; an editor must review the whole picture, merge duplicates, correct outdated content, delete obsolete content, and place stable knowledge at the correct audience layer. The goal is that the next human, the next agent, and downstream projects will not be misled by old documentation.

Do not downgrade the task to "adding a few lines of documentation." In AI collaborative development, code can be rewritten, but documentation and memory are the bridge across sessions and across agents. Incorrect memory will make the next agent act on wrong premises; chaotic docs will make the next person waste time re-inferring the system.

cs-docs-neat is not cs-doc-tutorial：cs-doc-tutorial writing a single developer / user guide;cs-docs-neat performs a global knowledge base hygiene check and sync at phase wrap-up.

Four layers of knowledge, four audiences

You must first understand the division of labor, otherwise you will only change CLAUDE.md / AGENTS.md and stop, leaving docs,.codestable/ , and memory aside.

Layer	Typical files	Readers	Responsibilities	Cost of not syncing
CodeStable workflow memory	`.codestable/attention.md`、`requirements/`、`requirements/CONTEXT.md（cs-domain 领域模型）`、`roadmap/`、`compound/`	CodeStable skills and project maintainers	Software lifecycle facts, long-term constraints, architecture status, planning, accumulation	Subsequent features / issues read outdated facts
Project agent entry point	`CLAUDE.md`、`AGENTS.md`, platform-equivalent files	AI agents in the current repository	Rules, commands, red lines, and documentation index that must be followed every time code is written	The next AI takes detours in the project
External reader documentation	`README.md`、`docs/`	Human colleagues, downstream developers, future maintainers	Onboarding, usage, integration, operations, architecture explanation	People or systems cannot correctly onboard / operate
External agent memory	Platform memory or global configuration for Claude / Codex / OpenCode, etc.	Reuse by a certain agent across sessions	Personal preferences, cross-project principles, temporary lessons, pointers to authoritative documentation	Personal memory bloats or the next session forgets historical principles

All four layers must be reviewed.CLAUDE.md / AGENTS.md is not a substitute for the CodeStable spec, but they are the entry points that agents will actually read, and they must stay in sync.

Graduation mechanism: pump stable knowledge upward

docs converge through in-place editing, while agent memory is naturally prone to append-only bloat. Without a reverse valve, stable knowledge will be trapped in dozens of loose memory files, neither entering context nor becoming documentation others can read.

Reverse valve = graduation (promote). If external memory or temporary records meet any of the conditions, merge the content into the corresponding project documentation, then delete the original memory or shrink it to a one-line pointer:

The same lesson on a topic recurs for the 3rd time: it is already stable knowledge, not a "recent pitfall."
The content is about "how the system works": it belongs in .codestable/requirements/CONTEXT.md, README, or docs.
Content is event records of the form "X launched / landed / in place": current facts go into docs / architecture, process goes into git log / changelog, and memory keeps no permanent files.
Content is project commands / red lines / environment traps: rules go into CLAUDE.md / AGENTS.md, and when necessary a single line goes into .codestable/attention.md。

One-sentence criterion:Does the next person taking over (not just the current agent) need to know this? If yes, it belongs in project docs; only if no can it stay in personal memory.

If memory files have type prefixes:reference_ can usually remain permanently resident;feedback_ graduates once stable;project_ is mostly event records, so prioritize graduating or deleting it.

`CLAUDE.md` / `AGENTS.md` is a rulebook, not a changelog

The most common failure mode: after every development session, historical narrative is added at the top of the agent entry: "2026-05-08 X feature launched, see docs/Y for details." It feels great once, but half a year later the actual rules have been pushed out of sight by 200 lines of history.

To judge whether a piece of information should enter the agent entry, ask:If the next AI writing code does not see this, will it make a mistake?

Example	Enter `CLAUDE.md` / `AGENTS.md`？	Reason
"Prisma queries are only written in `modules/**/data/`”	Yes	Violation is a boundary breach
"rsync single-file deployment must use the full target path"	Yes	The command trap will be stepped on repeatedly
"Bare running is prohibited `systemctl stop worker`”	Yes	Red line, incident-level
"2026-05-08 timelineAt launched, see docs/ARCHITECTURE.md for details"	No	Detailed mechanism is in docs; the agent entry only needs the index
"Retrospective details of fixing X bug"	No	A single incident belongs in learning / runbook or should be deleted

What should enter the agent entry: hard boundary rules, prohibited items, command quick reference, permission model, collaboration process, pointer table to in-depth docs, and pitfalls that will repeatedly affect implementation.

What should not enter: historical narrative, detailed mechanisms, single-incident retrospectives, bug fix ledgers, and "see docs/Z for details" pointer sentences already covered by the index table.

Phase 0: Size check (prevent bloat)

Before any sync action, first measure the key files:

wc -l CLAUDE.md AGENTS.md README.md 2>/dev/null
find docs .codestable -path '*/.git' -prune -o -name '*.md' -print 2>/dev/null | xargs wc -l

Then check external memory (if present):

wc -l <memory-dir>/MEMORY.md 2>/dev/null
wc -c <memory-dir>/MEMORY.md 2>/dev/null
du -sh <memory-dir> docs .codestable 2>/dev/null

Thresholds and handling:

File	Limit	What to do if exceeded
`CLAUDE.md` / `AGENTS.md`	About 300 lines / 15KB, or follow project constraints if stricter	First delete historical narrative; converge rules into tables; migrate detailed mechanisms to docs / `.codestable/`
`.codestable/attention.md`	About 150 lines	Keep only short must-read startup rules; graduate long explanations to decision / learning / architecture
memory index	Claude `MEMORY.md` ≤ 200 lines and ≤ 25KB	Excess parts may silently fail to load; compress through graduation, do not hard-delete stable knowledge
Single memory entry	About 100 lines	Split, delete, or promote the stable mechanism into project docs and reduce it to a pointer
Single docs file	About 1500 lines; if the project has a stricter limit, follow the project constraints	Split and build an index; if the user asks to confirm first, only list suggestions and do not split on your own

Additional inspection reveals an inversion of volume: the healthy state is thick project docs and thin memory. If memory is thicker than docs / .codestable/ , it usually means stable knowledge is still stuck in personal memory.

Execution order: first trim (break expansion) → then add this increment. Do not mix the two things: when trimming, ask "what should not be here"; when filling gaps, ask "what should be added here".

Phase 1: Mechanical enumeration (cannot be skipped)

First ls / find, then judge. Do not pick a few files based on impression.

Read .codestable/attention.md。
Enumerate .codestable/：
- ls .codestable/
- find .codestable -maxdepth 3 -type f \( -name '*.md' -o -name '*.yaml' \) | sort
Enumerate project root markdown:
- README.md
- CLAUDE.md
- AGENTS.md
- AGENTS.override.md
- TEAM_GUIDE.md
- .agents.md
Enumerate external docs:
- ls docs/ 2>/dev/null
- find . -maxdepth 2 -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' | sort
Check external agent memory paths. For a path quick reference, see references/agent-paths.md, and only read files that actually exist on the current platform.
Review this conversation, the current git diff, and recent commits to confirm what happened in this phase.

Maintain an internal checklist: mark each file as 评估过 / 要改 / 不用改 / 需用户确认. If a key document is missed, you cannot proceed to persistence.

Phase 2: Change impact matrix

Do not look only at what new facts were added in the conversation; look at which documentation layers the facts will affect. First check references/sync-matrix.md, then make a judgment.

Common mappings:

New API / route:CLAUDE.md / AGENTS.md quick reference + integration / dev guide + architecture routes.
New environment variable: agent entry environment variable table + README setup + runbook + downstream integration guide.
New database table / schema: architecture data model + dev guide; if necessary, add migration / testing rules to the agent entry.
New major feature: requirements / architecture / roadmap / user guide / dev guide may all be affected.
New long-term constraint: decision + agent entry execution rules; if it must be known on every CodeStable startup, then put it into attention.
Pitfall or debugging path: learning; if it will repeatedly affect implementation, then distill one line into the agent entry or attention.
Documentation structure change: keep README / docs index / agent entry documentation pointers in sync.

Be especially careful across projects: when upstream APIs, SDKs, subdomains, authentication, shared environment variables, or common components change, downstream project docs must also be aligned. Finishing changes in the current repository does not mean synchronization is complete.

Phase 3: Actual modification

You must actually modify files. Merely saying "here is how to change it" does not count as done.

Recommended order:

.codestable/ Authoritative layer: requirements / architecture / compound / attention.
README / docs: installation, usage, integration, and operations instructions for people and downstream consumers.
CLAUDE.md / AGENTS.md: rules, commands, red lines, and documentation index that agents must follow.
External memory: graduate, delete, shrink pointers; be extremely restrained with global configuration.

Editing principles:

Reduction is better than addition: if the net growth of the agent entry exceeds about 30 lines, that is a red flag; go back and check whether you are writing historical narrative.
Merging is better than appending: if the new information is an update to old information, modify the old section; before adding a new item, first grep the same keyword.
Deletion is better than retention: completed temporary plans, overturned decisions, expired memories, and one-off incident logs should be deleted or archived.
Graduation is better than internal shuffling: do not move stable memory around inside memory; merge it directly into project documentation.
Precision is better than verbosity: One memory states one thing.
Absolute time: Write the actual date YYYY-MM-DD, not "today / recently / last week".
Don't mix audiences: docs don't say "I remember last time"; the agent entry point doesn't copy the full docs text.
Don't duplicate pointers: if the same fact is written in detail in docs, it appears only once in the agent entry point, in the document index.

Writing rules:

.codestable/attention.md: Only put short rules that must be known every time the CodeStable skill starts.
.codestable/requirements/CONTEXT.md: Only write the current state, not future plans.
.codestable/requirements/: Write capability vision and boundaries, don't stuff in implementation details.
.codestable/compound/: Still use learning / trick / decision / explore; do not add a doc_type specific to this skill.
CLAUDE.md / AGENTS.md: Only put rules, commands, prohibitions, and indexes that the agent will use when writing code; do not write a changelog.
README / docs: aimed at people encountering the project for the first time, keep commands, APIs, environment variables, and code consistent.
Global config:~/.claude/CLAUDE.md、~/.codex/AGENTS.md Only change it when the user expresses a cross-project principle; project details must not be written globally.

When adding a capability, usually all four places need to be updated:

integration / dev guide: how to use it.
architecture: how it works.
runbook / README: how to run and troubleshoot.
handoff / changelog or roadmap: completed status.

Phase 4: Self-check list

After finishing the changes, go through each item; if any fails, go back and fix it.

Size / anti-bloat:

CLAUDE.md / AGENTS.md Net growth ≤ 30 lines; if exceeded, history narrative has been deleted / migrated.
No new historical entries of the form "X starts, Y goes live, see docs/Z".
Did not copy detailed mechanisms already in docs into the agent entry point.
.codestable/attention.md Was not written as a long essay.
A single memory does not exceed about 100 lines; stable content has graduated.
memory index (if any) ≤ platform threshold, Claude MEMORY.md ≤ 200 lines and ≤ 25KB.
No size inversion: memory should not be thicker than project docs / .codestable/ .

Completeness / anti-missed-change:

Every file enumerated in Phase 1 has a conclusion.
Every link in the memory index points to an existing file.
The memory file description matches the content.
memory / agent entry point / docs do not contradict each other.
Paths, commands, tools, and environment variables mentioned in the agent entry point actually exist in the code.
The README's install / run / test steps are consistent with the code.
New API: appears in both integration / dev guide and architecture.
New environment variable: appears in both README / runbook and agent entry point.
New database table: appears in both architecture data model and related development docs.
Cross-project impact has been searched and handled, or listed with the reason for not handling it.

No relative-time remnants:

rg "今天|昨天|刚刚|最近|上周|today|yesterday|recently" .codestable README.md docs CLAUDE.md AGENTS.md 2>/dev/null

git diff Only includes changes related to this documentation / knowledge base cleanup.

Phase 5: Change summary

After all files are modified, give the user a summary:

## 文档整理完成

### CodeStable
- `.codestable/attention.md` — ...
- `.codestable/requirements/CONTEXT.md...` — ...
- `.codestable/compound/...` — ...

### Agent 入口
- `CLAUDE.md` — ...
- `AGENTS.md` — ...

### README / docs
- `README.md` — ...
- `docs/...` — ...

### 外部记忆
- 更新：...
- 删除：...
- 毕业：...

### 未处理
- ...（需要用户确认或刻意跳过）

Only list actual changes. For levels not changed, just write "no changes".

Special cases

The project does not yet have a README or CLAUDE.md / AGENTS.md: if there is already runnable code, create one; if it is still in early exploration, skip it and explain.
The conversation produced no new facts: still review whether existing documentation is outdated, conflicting, or contains relative time.
An undecidable contradiction appears between memories: list it under "unresolved" and let the user decide; this is one of the few cases that require user involvement.
Cross-project changes: run Phase 1 for each project; do not assume that changing upstream documentation means downstream does not need changes.
Discovering something was missed in a previous sync: fix it directly; do not say "that was not part of this conversation."
The user explicitly requests confirming the splitting of a large document first: provide only splitting suggestions and their rationale; do not reorganize without authorization.

Relationship with other skills

Skill	Relationship
`cs-onboard`	Onboard first when the repository is not yet connected or needs migration and archiving; this skill is not responsible for building the skeleton
`cs-doc-tutorial`	Suggest or trigger when missing external guides are found; if an existing guide is outdated, it can be fixed directly with a small edit
`cs-doc-api`	Suggest libdoc when the public API reference is missing or outdated; this skill does not generate API references in bulk
`cs-keep` / `cs-keep` / `cs-keep` / `cs-keep`	Use these existing doc_type values when discovering stable knowledge that needs to be archived
`cs-note`	When one or two lines of must-read hard constraints for startup are found, attention can be suggested or updated
`cs-feat-accept` / `cs-issue-fix` / `cs-feat-ff`	Trigger neat after the phase ends to perform a global sync

Reference materials

references/sync-matrix.md — mapping from change types to documentation layers
references/agent-paths.md — quick reference for external agent memory and configuration paths