guide-updater skill

Overview

This skill updates a project guide by persisting new, reusable writing insights from a conversation directly into the specified guide file. It aims to keep terminology consistent, structure stable, and documentation reproducible and verifiable. Calls must include the guide file path to apply changes.

How this skill works

On invocation with a guide path, the skill extracts atomic writing insights from the dialog and maps each into a single actionable bullet plus a one-sentence purpose. It locates the best insertion point using a guide-structure map and applies a minimal incremental patch (typically 1–3 bullets or a short clarifying sentence). After writing, it runs or recommends lightweight validation to ensure key headings and structure remain unchanged.

When to use it

• When the user explicitly asks to “update project guide”, “sync guide”, or “persist insights to the guide”.
• After a review discussion that produced reusable rules, terminology clarifications, or verification criteria.
• When small, verifiable additions are needed without reshuffling existing guide structure.
• When you need to enforce consistent terminology, evaluation rules, or reviewer Q&A don't appear in the guide.
• When draft insights must be preserved immediately to avoid future rework.

Best practices

• Always supply --guide-path (or a natural-language guide path) when calling the skill.
• Prefer minimal patches: add 1–3 bullets or append one clarifying sentence to an existing bullet.
• Do not create new top-level '##' headings; merge into existing sections that match the insight.
• Attach a one-line purpose to each new bullet (e.g., unify wording, reduce review risk, ensure reproducibility).
• Mark unverified factual claims as 'to be verified' rather than inventing details.
• Run the provided validation script after updates to confirm the guide’s key headings remain intact.

Example use cases

• A reviewer suggests a consistent phrasing for method descriptions—persist the phrasing and state the purpose as 'unify terminology'.
• During discussion a new evaluation metric is agreed—add a bullet under 'Basic Principles' with verification criteria.
• A lab member proposes a risk mitigation step—add it under 'Research Risks' with the purpose 'risk control'.
• Clarify an abbreviation or casing rule by adding an entry to 'Naming and Terminology'.
• Capture a candidate reviewer Q&A under 'Reviewer Questions and Answers' to prepare consistent responses.

FAQ