cs-guide

cs-guide

Required reading at startup

Before making any judgment or taking any action, first read .codestable/attention.md; if missing, treat the skeleton as incomplete, prompt to fill it in first or run cs-onboard, and do not fall back to an external AI entry file.

Code solves the problem; documentation lets others use it to solve the problem. The spec records "what was done and why it was done this way", but downstream developers and end users do not need to—and should not—read the spec; they need publishable guides oriented to their own roles. guidedoc is exactly about starting from the spec and the code to write guides that readers can truly use.

Two tracks

Track	Target readers	Typical content	Output path
`dev-guide`	Contributors, integrators, downstream developers	Local setup, architecture explanation, API description, extension methods	`docs/dev/{slug}.md`
`user-guide`	End users	Feature overview, operating steps, concept explanations, FAQs	`docs/user/{slug}.md`

Track selection starts from "who reads it"—the same feature often needs both: API changes go into the dev-guide, and the corresponding user operations go into the user-guide.

Paths docs/dev/ and docs/user/ are the default conventions; if the project already has its own docs structure, follow the project—confirm before starting.

Trigger timing

Situation	Description
End of feature-acceptance	Proactively push: if Section 2 of the plan (interface contract) has changes, ask "Do you need to update the dev-guide?"; if Section 1 (user-visible behavior) has changes, ask "Do you need to update the user-guide?"
User proactively triggers	"write docs", "guidedoc", "add a developer guide"
After onboard is complete	A new repository can trigger completion of the basic documentation skeleton

A one-sentence proactive push is enough; if the user says "no need", do not mention it again—pushing multiple times makes users feel the AI is adding drama.

Paths involved

guidedoc artifactsare not under .codestable/ —guides are publishable artifacts for external readers and are separate from spec artifacts.——The guide is a publishable artifact for external readers, separate from spec artifacts.

dev-guide → docs/dev/{slug}.md
user-guide → docs/user/{slug}.md

File naming {slug}.md(English lowercase hyphenated,no date prefix)—guides are continuously updated and managed by topic.

Retrieval:

python .codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
python .codestable/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}

YAML frontmatter

---
doc_type: dev-guide | user-guide
slug: {英文连字符}
component: {关联模块名或 feature slug}
status: draft | current | outdated
summary: {一句话描述涵盖什么}
tags: []
last_reviewed: YYYY-MM-DD
---

status three states:draft pending review;current currently valid;outdated the corresponding code has changed but the documentation has not kept up (keep the original text, mark it, and push an update).

Documentation format

dev-guide body structure

## 概述
一段话描述功能定位和适用场景。

## 前置依赖
集成此模块所需的环境、依赖或配置（如有）。

## 快速上手
最小可运行示例。代码优先文字辅助。

## 核心概念
（可选）理解接口 / API / 模块行为所需的关键术语和设计决定。

## 接口参考
主要 API / 配置选项 / 事件 / 钩子。表格或逐项列举。

## 常见场景
2-4 个实际使用场景代码示例，覆盖 happy path 和常见边界。

## 已知限制与注意事项
（可选）边界、性能考虑、已知 bug 绕过方式。

## 相关文档
关联的 user-guide、方案 doc、架构 doc 或外部参考。

user-guide body structure

## 功能简介
一段话描述功能是什么、解决什么问题。

## 前置条件
（可选）使用前的前提（账号权限、需先完成的操作）。

## 如何使用
步骤化操作。每步一行，关键操作配截图占位（`![描述](./assets/xxx.png)` 或注明"此处需截图"）。

## 常见问题
Q: ...
A: ...

## 相关功能
（可选）关联功能跳转链接或说明。

Workflow steps

Clarify the task scope—track (dev / user / both) + coverage scope (new writing or update) + information sources (does the plan doc already exist? Is there already a guide for the same component? Which code needs to be read?)
Collect inputs—read the plan doc (focus on Section 0 terminology, Section 2 interface contract, Section 1 user-visible behavior) + search-yaml.py Search docs/ to confirm whether an existing guide exists. If an existing guide is found, mark it outdated → the task is classified asupdate
draft——Draft according to the corresponding track structure, frontmatter status: draft. Constraints: write only content aimed at the target readers——do not carry over the "implementation notes" or internal design from the solution doc; terminology must be consistent with Section 0 of the solution doc; code examples must come from actual code and must not invent interfaces
User review——Present the draft and confirm section by section the coverage / accuracy of descriptions / whether there are places readers cannot understand
Write to disk——After the user gives the go-ahead: write to the path;status: current + last_reviewed the same day; when updating an existing document, make minor edits directly, but for major changes (structural reorganization / adjustment of reader targeting) first set the old document to status: outdated keep it for reference and then write a new one

Relationship with other workflows

Source	Relationship
`cs-feat-accept`	After acceptance, proactively push: interface changes to dev-guide, user-visible changes to user-guide
`cs-feat-design`	Section 2 of the solution is the main information source for dev-guide; Section 1 is the main information source for user-guide
`cs-onboard`	After a new repository is onboarded, the basic documentation skeleton can be completed
`cs-arch` (check)	When inconsistency between design and code is detected, the corresponding guide should be marked in sync as `outdated`
`cs-decide`	The technology choices referenced by dev-guide should come from decisions and must not be independently invented
`cs-trick`	If dev-guide usage examples overlap with tricks, cross-reference them instead of writing them repeatedly
`cs-libdoc`	The guide references libdoc entries for detailed reference; libdoc is component reference, guidedoc is task tutorial

Common pitfalls

Copying the original text of the "implementation notes" from the solution doc into dev-guide——that is internal spec
Creating a new guide without checking for an existing guide——there may be two conflicting versions
After writing status still draft——writing to disk must change current
The code has been updated but the relevant guide is still current——should be marked outdated and push the update
dev-guide and user-guide content overlap heavily——one of them has the wrong positioning
Using guide to store spec information (invariants / test constraints / root cause analysis)——this type of content belongs to .codestable/