cs-libdoc

cs-libdoc

Required reading before starting

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.

guidedoc teaches you "how to use X to do Y"; libdoc tells you "what each part of X looks like and how to configure it".

A mistake in guidedoc may just be unclear expression, but a mistake in libdoc is simply wrong—the information source is the source code itself, and types / default values / signatures all have a single correct answer.Core rules: don't guess, don't copy and rename, read the source code independently for each entry。

Comparison with guidedoc

	guidedoc	libdoc
Nature	Task-oriented (Tutorial / How-to)	Reference-oriented (Reference)
Answers	"How to use X to achieve a certain goal"	"What each part of X looks like and how to configure it"
Granularity	One feature / one scenario per document	One entry per document
Information source	Solution doc + user knowledge	The source code itself(types / comments / default values)
Order of magnitude	A few to a dozen or so documents	Dozens to hundreds of documents

Complementary: guides reference libdoc for detailed reference ("see xxx for the full props"), and libdoc's "related entries" link back to guides.

"Entry"

Project type	Entry granularity
UI component library	One component = one entry
Utility function library	One module or function family = one entry
API Client	One endpoint family = one entry
CLI tool	One subcommand = one entry

Confirm the entry granularity during the initialization phase and keep it consistent afterward—if the granularity keeps changing, the manifest and search will both become a mess.

Paths involved

libdoc artifactsnot under .codestable/ under—API reference is a publishable artifact aimed at external readers.

Entry documents → docs/api/{slug}.md
Entry manifest → docs/api/manifest.yaml

docs/api/ is the default convention; if the project already has another convention (reference/ / components/), follow the project—confirm before starting.

manifest / templates / source extraction

Reference materials are in the same directory reference.md：

manifest.yaml Full format and status semantics
Entry document frontmatter and body template
Source extraction checklist (interface signatures, default values, export methods, etc.)

The body of this skill only retains process constraints:libdoc uses the source code as the source of truth, does not guess, and does not copy the previous entry and rename it。

Workflow

Phase 1: Initialization—scanning and manifest

Confirm project type + entry granularity + output path
Scan the source code directory—read the file structure under source_root , identify public exports and group them logically
Generate manifest.yaml—all entries initially status: pending; after writing to disk validate-yaml.py --file docs/api/manifest.yaml --yaml-only validation; show to user for review
User confirms scope—can be marked skipped(internal implementation) / adjust category / merge or split

Phase 2: Generation

Mode A: Single-entry mode

Suitable for 1-3 entries or a first trial run to confirm quality.

Select entry → read source_files → generate per template → user review → write to disk → validate-yaml.py --file {路径} --require doc_type --require entry --require status → manifest corresponding entry status: current

Mode B: Batch mode

Suitable for a large number in the list pending。

Produce samples first—select 2-3 representative entries from the list (different categories) and go through "read source code → extract → generate per template" and write to disk, status first draft(do not go directly to current—in batch mode the samples are "style reference samples" and are switched to current together with the overall review)
User confirms quality standard—review these 2-3 pieces to confirm template / level of detail / style.This step cannot be skipped—all 50 pieces would be written in vain just because the style the user wants is different
Batch generation—the remaining pending go through "read source code → extract → generate" one by one, subagents can be used in parallel; each entry status: draft
Overall review—after batch completion show an overview (entry count / skipped count / pending-confirmation count); before review first validate-yaml.py --dir docs/api --require doc_type --require entry --require status batch validation
Confirm and finalize—after user confirmation, change both the samples and the batch output to status: current

Batch mode hard rules：

Each entry reads source code independently—even in batch mode, copying the previous one and renaming is not allowed. Two interfaces that look very similar often have subtle differences
Sample confirmation cannot be skipped
Source code structure is special (dynamic export / code generation), temporarily mark skipped add note—documentation produced by hard guessing is more harmful than no documentation

Phase 3: Incremental update

Sync documentation after code changes. Choose any of three entry points:

search-yaml.py search status=outdated—architecture check or those already marked by the last update
Compare manifest.yaml in last_scanned source files changed after
search-yaml.py --sort-by last_reviewed --order asc proactively review in order of longest time since review

Re-read source code → compare with existing documentation → incrementally update changed parts → validate-yaml.py validation → status: current + last_reviewed same day.

Relationship with other workflows

Source	Relationship
`cs-feat-accept`	After acceptance, new/modified public library interfaces → push "need to update libdoc?"
`cs-guide`	guide references libdoc for detailed reference; libdoc "related entries" link back to guide
`cs-arch` (check)	When an interface change is detected but libdoc is not synced, mark the corresponding entry `outdated`, handled by Phase 3 of this skill
`cs-feat-design`	Section 2 of the plan can serve as a supplementary information source for libdoc (but source code prevails）
`cs-trick`	When libdoc "notes" overlap with tricks, cross-reference instead of writing duplicates

Exit conditions

Phase 1: manifest.yaml has been written to disk + user has confirmed scope (including skipped reasons) + granularity and output path have been confirmed

Phase 2 single entry: entries generated according to the template + frontmatter complete + API reference section information sourced from source code extraction (not fabricated) + user confirmation + manifest updated

Phase 2 batch: template samples (2-3 articles) have received user confirmation + all pending entries have been generated or marked skipped + the user has done an overall review + the status of all manifest entries has been synced

Phase 3: all outdated entries have been updated or confirmed as not needing updates + no residual outdated in the manifest (unless the user explicitly defers)

Common pitfalls

Writing documentation without scanning the inventory first—may miss or duplicate items
Writing the API reference without reading the source code—the core value of libdoc is accurately reflecting the source code
Copying the previous entry and renaming it—subtle differences are bound to be missed
Skipping template sample confirmation in batch mode—all 50 articles end up written in vain
Writing spec information (invariants / test constraints) into libdoc—belongs to .codestable/
libdoc and guidedoc content overlap heavily—one of them has the wrong positioning
manifest.yaml Directly deleting lines—change status: skipped and write a note
Writing documentation for a source code interface that does not exist—use the source code as the source of truth, do not fabricate