guide-updater

Project Guide Updater

Collaboration Agreement with bensz-collect-bugs

When a bug caused by a design flaw in this skill appears in the user's environment, preferentially use bensz-collect-bugs to record it per the specification in ~/.bensz-skills/bugs/. It is strictly forbidden to directly modify the source code of the installed skill in the user's local Claude Code / Codex.
If the AI can still complete the user's task via a workaround, it should first record the bug, then continue completing the current task.
When the user explicitly requests a public reporting action such as "report bensz skills bugs," invoke the local gh and bensz-collect-bugs, and upload only the newly added bugs to huangwb8/bensz-bugs; do not pull / clone the entire bug repository.

Consolidate reusable writing insights newly generated in the conversation into the project guide file in real time, keeping terminology consistent, the structure stable, and the content verifiable and reproducible.

How to Use

When invoking this skill, youmustspecify the guide file path in the parameters:

/guide-updater --guide-path <路径>

Or in natural language form:

"Update the project guide (path: projects/MyProject/项目指南.md)"
"Sync these contents to the guide file docs/写作指南.md"

Prerequisites

Do a quick self-check before each update:

Do not add new ## -level headings; only "blend" new points into existing subsections/lists.
Do not change existing heading text, numbering, or order; do not rearrange large amounts of content for the sake of "tidying up for aesthetics."
By default, write new content as 1 or a small number of bullets, closely following the wording and tone of adjacent entries.
When facts/literature are involved: write only verifiable information; if it cannot be verified, mark it as "pending verification"—do not fabricate detailed information.

Extract "Atomic Insights"

Break the user's expression into several "ready-to-write" points, each containing only one claim/rule/writing approach.
Attach 1 sentence to each point stating the "purpose of writing it into the guide" (e.g., unify terminology / preempt reviewer challenges / reproducibility / risk control).

Choose Where to Integrate

When more detailed placement rules are needed, first read skills/guide-updater/references/guide-structure-map.md before acting.
Writing principles/prohibitions/sentence patterns → ## 写作哲学
Terminology, abbreviations, capitalization, core concept definitions → ## 命名与术语
Method chains, verification criteria, evaluation metrics → ## 基本原理
Paradigm positioning, comparison coordinate system, differentiation points → ## 文献综述与创新性
Which section specifically to write to (document structure mapping) → ## 落点清单
Review Q&A wording → ## 评审专家可能的问题及回答
Risks and countermeasures → ## 研究风险
"Verifiable fact anchors" (source code, parameters, workflows) → ## 附录

If unsure where to put it: preferentially place it where it will "most reduce future writing rework"; if still unsure, first ask the user, "Would you prefer this to be consolidated as writing philosophy / technical approach / risk control?" before modifying the file.

Write as a Minimal Patch

Only make "incremental patches": add 1--3 bullets or append 1 clarifying sentence to the end of an existing bullet.
Do not open large new blocks of long text; if the insight is very large, first break it into multiple bullets and distribute them across the corresponding subsections.
Stay consistent with existing terminology (refer to the project's existing glossary).

Post-update verification

Run python skills/guide-updater/scripts/validate_guide.py <指南文件路径>(or manually confirm that the key ## headings still exist).
Check whether any ## -level headings were unexpectedly added or whether a "start-from-scratch" new structure was introduced.

Resources

Directory	Purpose
`scripts/`	Verify whether `项目指南.md` retains the key structure and necessary headings
`references/`	Record the structure mapping and placement rules to avoid repeatedly determining placement positions