research-guide-updater

Project Guide Updater

Prerequisites

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".
• New content should by default be written as 1 or a small number of bullets, closely following the style and tone of adjacent entries.
• When facts/references are involved: write only verifiable information; if it cannot be verified, mark it as "to be verified"; do not fabricate detailed information.

Process

Input

Provide the necessary input according to the user request and configuration file; for missing information, list it explicitly and stop steps that depend on that input.

Execution Steps

• When a bug caused by a design flaw in this skill appears in the user's environment, prefer to use bensz-collect-bugs to record it per the specification in ~/.bensz-skills/bugs/; strictly do not directly modify the source code of the skill already installed 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 public reporting actions such as "report bensz skills bugs", call the local gh and bensz-collect-bugs, and upload only the newly added bug to huangwb8/bensz-bugs; do not pull / clone the entire bug repository.

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

Old name guide-updater is retained only as a prompt compatibility alias; when installing a new version, the system-level old directory will be cleaned up.

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

/research-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"

• Break the user's expression into several "ready-to-write" points, each containing only one claim/rule/writing approach.

• Attach to each point 1 sentence on "the purpose of writing it into the guide" (e.g., unifying terminology/preventing review challenges/reproducibility/risk control).

• When more detailed placement rules are needed, first read skills/research-guide-updater/references/guide-structure-map.md before acting.

• Writing principles/prohibited zones/sentence patterns → ## 写作哲学

• Terminology, abbreviations, capitalization, core concept definitions → ## 命名与术语

• Method chains, verification criteria, evaluation metrics → ## 基本原理

• Paradigm positioning, reference coordinate system, differentiation points → ## 文献综述与创新性

• Which section specifically to write into (document structure mapping) → ## 落点清单

• Review Q&A terminology → ## 评审专家可能的问题及回答

• Risks and countermeasures → ## 研究风险

• "Verifiable fact anchors" (source code, parameters, processes) → ## 附录

If unsure where to put it: prefer the position that "best reduces future writing rework"; if still unsure, first ask the user "which category would you prefer this to be distilled as: writing philosophy/technical roadmap/risk control?" before modifying the file.

• Only make "incremental patches": add 1--3 new bullets or append 1 clarifying sentence to the end of an existing bullet.
• Do not start a new long passage; if the insight is substantial, 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).

Table of Contents	Purpose
scripts/	Verify 项目指南.md whether the key structure and required headings are preserved
references/	Record the structure mapping and placement rules to avoid repeatedly deciding where to place content

Output

Output the deliverables promised by the Skill description, and specify the format, path, and failure return form.

Output Management

Intermediate files for new tasks of this Skill are uniformly written to ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/. The same task reuses one task root directory; only multi-Skill collaboration creates shared/. Formal deliverables are not written to this directory; hidden historical directories are only allowed to be explicitly read for compatibility, migrated, or cleaned up.

Verification

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

Failure and Recovery

Preserve error evidence and completed artifacts; retry from the most recent failed step only after the input, environment, or external dependencies have recovered.

Constraints

Comply with the following common constraints, and enforce this Skill's specific boundaries.

Common Hard Constraints

• When a task needs to be persisted to disk, use the unique ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ root directory; put shared materials in shared/, and put Skill-specific materials in that Skill's input/、output/、log/。
• Formal deliverables, source code, and formal plans are stored according to project conventions and are not written to the task workspace; without authorization, do not overwrite, delete, migrate, or write remotely.
• Project maintenance changes check BAC availability and record requirements, AI outputs, tool results, file changes, and verification summaries; BAC only performs process auditing and does not replace attribution, responsibility, or compliance judgment.
• Do not record API Keys, access tokens, passwords, Cookies, environment/credential files, private Prompts, identity information, local usernames, hostnames, or unnecessary large raw data.
• File paths must be normalized and restricted to the authorized project scope; external URLs, subprocesses, and network access follow least privilege to prevent path traversal, SSRF, and command injection.
• The Skill version is recorded only in its own config.yaml:skill_info.version; changes to public APIs, protocols, directories, or configurations are synchronized with the documentation and CHANGELOG.md。
• Only hand design flaws in the Skill or Bensz infrastructure itself to bensz-collect-bugs; first write them in desensitized form to ~/.bensz-skills/bugs/, do not interrupt the current task, report publicly only when the user explicitly requires it, and do not directly modify the Skill source code already installed by the user.

Skill-Specific Constraints

Do not exceed the scope declared by this Skill description and the process above; do not disguise unverified information as definite conclusions.