This skill is used, after the requirements, plan, and implementation loop is closed, to preserve the already-implemented business behavior in docs/spec/. The focus is not restating the source code, but helping future maintainers understand the final specification: what behavior the requirements became, how the code supports this behavior, which contracts are affected by changing it, and what real boundaries currently exist.
Applicable scenarios
When the user asks to generate a docs/spec/ specification document based on a certain requirement, plan, diff, file, tool, service, interface chain, or module implementation, prefer to use this skill.
Also use this skill when the user explicitly asks to summarize the core logic, detailed code logic, impact scope, current boundaries, TODO comments, file names, method names, line numbers, or to preserve this round of implementation into documents.
If the user merely asks what a piece of code does, you can answer briefly and directly, without generating a complete specification document. Only when the user asks to preserve documents, write to docs, generate a summary, update the spec, or organize module descriptions does the full workflow begin.
Non-goals
This skill is only responsible for preserving already-clarified requirements, plans, and implementations as specification documents. It is not responsible for incidentally modifying business code, redesigning solutions, or performing a complete code review.
If during reading you find obvious bugs, risks, inconsistencies between implementation and requirements, or conflicts between old documents and the current implementation, point them out objectively before preserving the specification. Do not force an implementation that does not meet the requirements into a new specification, and do not write the specification document as a problem list or refactoring plan unless the user explicitly requests it.
Readability check before writing
Each time content is added or updated, you must first polish and verify all text to be written.humanizer-zh When the skill is available, you must call it, fully read and apply its SKILL.md. If it has already been read for the current task and the file has not changed, you may continue using it; if it is unavailable, complete the check according to the plain-language rules below and continue writing.
The scope of handling includes all specification body text, index descriptions, table descriptions, TODO summaries, and other explanatory text written this time. First form a draft based on the requirements, plan, and implementation, then polish it according to the above rules, verify the meaning, and write it. It is not acceptable to polish only the final reply, document summary, or some sections.
Preserve requirements, implementation status, conditions, negations, source attribution, and degree of certainty; do not write plans or speculation as implemented behavior. Code, identifiers, commands, paths, line numbers, URLs, link targets, and structured data remain unchanged; existing headings and anchors are handled according to that skill's file protection rules. If the text is modified again after writing, the modified parts must also undergo the same handling.
humanizer-zh When unavailable, first explain the final behavior using common words and short sentences, then explain the key conditions, flow, and impact; explain necessary terms in plain language, delete empty words and repetition, and do not add unverified information. Read through from the perspective of a future maintainer, confirming that the module behavior can be understood without opening the source code. Continue to complete the writing, and briefly state in the report that plain-language rules were adopted, without claiming that the skill was called.
Workflow
Proceed in the following order. The purpose of this process is to first confirm where the specification document should be placed, then confirm what the final behavior is, and only then write the document.
用户输入 / 本轮 diff / 指定文件
│
▼
读取需求、plan、实现入口或 git diff
│
▼
读取 docs/spec/index.md 和相关子索引
│
▼
读取目标模块已有规格文档
│
▼
顺着 import、schema、type、service、prompt、controller、query 查直接依赖
│
▼
判断更新旧文档、新建文档，还是先反馈冲突
│
▼
形成正文和索引草稿，按可读性检查规则润色并核对含义
│
▼
写入 docs/spec，并同步更新索引
│
▼
检查 git diff / git status，确认只产生预期文档变更
Context Reading Criteria
First confirm the available context. Prioritize reading the requirements description, plan document, implementation files, or the current round's git diff provided by the user. If the current conversation already contains the requirements and plan, they can be used directly; if not, read the corresponding documents or code according to the path specified by the user.
Then read docs/spec/index.md, to confirm the existing document location for the target business domain. If the target directory has a sub-index, also read the sub-index; for example, AG-UI-related content requires reading docs/spec/ag-ui/index.md。
Next, read the existing specification documents of the target module. The goal is to determine whether this consolidation should update an existing document, add a new standalone document, or merge into a more appropriate topic. Do not create a new document based solely on the code path without understanding the existing spec.
Then read the main file specified by the user or the current round's implementation diff. Do not guess responsibilities from the file name alone, and do not write a summary based only on existing memory.
After reading the main file, continue tracing direct dependencies along imports, core function calls, schemas, types, services, prompts, controllers, and query methods. The goal is to see the real execution path of the current module in full, but do not spread indefinitely into unrelated modules.
If the main file is only the entry layer, continue to find the logic, service, or query files that actually carry the business logic. When summarizing, it is necessary to clearly state what the entry layer does and what the core business layer does; do not mistakenly write the entry layer as the entire logic.
When encountering schema, type files, and prompt files, it is necessary to determine whether they affect input parameters, output parameters, invocation methods, structured output, frontend protocols, or presentation criteria. As long as they have an impact, they should be included in the impact scope section.
When checking for TODOs, search the main file, directly dependent files, and related files under the current module directory. The search keywords should at least cover TODO, todo, FIXME, fixme, and to-do. If none are found, explicitly state that none were found; do not fabricate to-dos.
Decision Criteria
When encountering document placement or conflicts, judge according to this table. A table is more suitable than prose for giving the model stable execution, because each row is a clear input condition and action.
| Situation | Action | Reason |
|---|---|---|
| There is already a spec on the same topic, and the current implementation only supplements or corrects this topic | Update the existing document | Avoid splitting the same specification into multiple conflicting documents |
| There is no spec on the same topic, but the target domain already has a directory or sub-index | Create a new topic document and update the corresponding index | Enable future maintainers to find the new specification from the index |
| The target content spans multiple business domains, and each business domain has independent maintenance value | Update the corresponding module documents separately | Avoid one module document carrying the key context of other modules |
| The requirements, plan, code, and old spec conflict | Point out the conflict first; do not directly write it as a new specification | A spec records confirmed stable behavior, not packaging conflicts as conclusions |
| The user did not provide clear requirements or a plan, and only gave code | Omit the requirements implementation section and only write the stable behavior reflected by the implementation | Do not fill in requirements out of thin air, to avoid the document creating business goals that do not exist |
| The user only temporarily asked what the code does, and did not request documented knowledge to be persisted. | Answer directly and do not enter the full documentation-writing process. | Avoid turning lightweight Q&A into excessive documentation. |
Specification persistence principles
Specification documents persist the final behavior, not a code play-by-play. The business goals in the requirements and plan should be converted into a stable definition, and code serves only as evidence for that definition.
If there is a conflict among the requirements, plan, code, and old spec, do not default to treating the code as authoritative. First point out the conflict and explain which side lacks support; only when the user explicitly confirms that the current implementation meets the requirements should the current implementation be persisted as the new specification.
If the old spec is already outdated, prioritize updating the relevant sections in the old document. Do not bypass the old document and write a new document with overlapping semantics, to avoid docs/spec/ containing specifications that contradict each other.
If the target module does not yet have a corresponding spec, writing to docs requires adding a new document and updating docs/spec/index.mdin sync. If the target directory has a sub-index, it should also be updated in sync.
Document structure
When generating a specification document, the first section must be the core logic. This section should first explain the module's positioning, then explain the final behavior delivered by the requirements, and then explain the main flow and key design trade-offs. The writing should read like setting out the specification for future maintainers, not like translating code line by line.
Sections can be organized according to the table below. Sections that can be omitted should be omitted only when there is no real basis; do not invent content just to complete a template.
| Section | What to write | When to omit |
|---|---|---|
| Core logic | Module positioning, final behavior, inputs, outputs, main flow, key design trade-offs | Do not omit; this is the backbone of the specification document |
| Requirement delivery | How the key goals of the requirements or plan land in the implementation, and mark the key code locations | Omit when the user has not provided clear requirements or a plan |
| Detailed code logic | Write the entry point, parameter handling, core orchestration, key algorithms, and output assembly in call order, with filenames and line numbers | Do not omit, but compress it; do not translate the source code line by line |
| Impact scope | Real dependencies such as schema, type, prompt, callers, query, frontend protocol, event semantics, checkpoint, and cache | When there are no real dependencies, it may be written briefly; do not write generic risks |
| Current boundaries | Existing boundaries such as the empty-result protocol, field definitions, permissions, time windows, precision, deletion semantics, and run/replay differences | Omit when there are no clear boundaries |
| TODO comment summary | The locations and meanings of TODO, FIXME, and pending comments; when there are none, write the search scope and result | Do not omit the search results; writing that none were found is allowed |
Recommended section template
The document can be organized in the following order.
# 模块总结
## 核心逻辑
Explain what this module is responsible for, what behavior the requirements ultimately delivered, what the inputs are, what the outputs are, how the main flow proceeds, and what the core design is.
## 需求落地
If there are clear requirements or a plan, explain which code paths support each key requirement point. Omit this when there are no clear requirements or plan.
## 详细代码逻辑
Write in the order of entry function, permission or parameter handling, core orchestration functions, key algorithm functions, and output assembly. Each section should include the file name and line number.
## 影响范围
Write about the schema, type, prompt, callers, query layer, business aggregation layer, event protocol, frontend protocol, checkpoint, cache, and related modules that would be affected by changes to the current module.
## 当前边界
Write about boundaries that are already reflected in the code and are easy to misunderstand during future maintenance. If there are no obvious boundaries, this can be omitted.
## TODO 注释归纳
Write about any TODOs, FIXMEs, or pending comments found during inspection. If there are none, state the inspection scope and result clearly.
Detailed writing requirements
Keep the whole text human-friendly. Sentences should be short, and the logic should flow smoothly. State the conclusion first, then the details. Do not paste large chunks of source code into the document unless the user explicitly asks for source code examples.
Keep code references restrained. Prefer citing file paths, method names, and line numbers instead of pasting large amounts of source code. Usually one line number reference per key point is enough.
Do not overcomplicate. Do not expand into unrelated history, architectural background, theoretical explanations, or speculation not present in the current code just to appear complete.
Do not repeat the same information. After the module positioning has been covered in the core logic, the detailed code logic should only add the execution order and key functions, without repeating the same introduction.
Be specific when writing about impact scope. Clearly state that a certain schema affects structured output validation, a certain type affects the TypeScript type contract, a certain prompt affects when the model calls a tool, a certain query affects field semantics, and a certain event affects frontend recovery or replay.
Be honest when writing about current boundaries. Write clearly about boundaries that have already been implemented, and do not include unsupported future plans in the specification.
Be restrained when writing TODOs. TODOs are a supplement to the current boundaries, not the main focus of the document. If there are none, then there are none; do not force problems just to make the section complete.
Line number requirements
Line numbers must come from actual reads or search results. Do not write line numbers from memory.
If a file has just been edited, re-read or search the relevant snippets to ensure the line numbers are not outdated.
If line numbers are dense, do not mark every line. Select key method definitions, key branches, key calls, and key return structures.
When outputting to a file
Summary documents are stored by default under docs/spec/* in the corresponding module directory. First read docs/spec/index.md, then find the most appropriate module folder based on the business domain of the main file, the business domain of the requirement, and the call chain. For example, MCP course-related content goes under docs/spec/mcp/course, and AG-UI-related content goes under docs/spec/ag-ui or its subdirectories. When a summary involves multiple modules at the same time, the documents under the corresponding directories of those modules need to be updated separately. Do not place it in only one module and cause missing context.
Document naming should make the topic obvious at a glance. By default, use Chinese names such as "Business Name Summary.md" or "Business Name Tool Summary.md", for example 课次详情工具总结.md. If a document on the same topic already exists in the target directory, prefer updating the existing document rather than creating a new document with overlapping content. Only create a new file when the topic is truly independent or the user explicitly requests a new one.
If the user requests writing to docs or a specified path, first check the naming and style of existing documents in the target directory. New documents should follow similar naming and expression styles as much as possible, but do not overwrite existing files unless the user explicitly requests overwriting.
Before writing, confirm whether the target file already exists. If it exists, read the content first, then decide whether to overwrite, append, or update. When the user has not said to overwrite, prioritize updating documents on the same topic; only when there is no document on the same topic should a new file with a clear semantic meaning be created.
After adding or migrating the docs/spec/ document, you must synchronously update docs/spec/index.md. If the target directory has its own index.md, that sub-index must also be synchronously updated.
After writing, check git diff or git status to confirm that only the expected document changes were produced. If you find other existing changes in the workspace, only state that they exist; do not handle them on your own.
Quality standards
A qualified specification document should let readers know the module's final behavior, how requirements are implemented, the main flow, key algorithms, affected contracts, current boundaries, and TODO status without opening the source code.
A qualified specification document should also let readers quickly jump to the source code based on the file paths and line numbers in the document when they want to continue investigating.
If the document reads like a line-by-line translation of the source code, it is not good enough. It should be re-compressed into module behavior, data flow, key constraints, and scope of impact.
If the document only describes what the code does but does not explain what stable behavior the requirements have become, it is also not qualified. The requirement definition, specification definition, and affected contracts should be added.