--- name: refine-doks description: "Audit and refine existing project documentation in `base-dir` (from `./doks.yml`) against Doks guidelines for glossary (`*.glossary.md`), user story (`*.story.md`), and architectural (`*.architecture.md`) files. Lists all files needing updates and processes one file at a time (updating only its body while allowing cross-reference updates in other files). Use when asked to refine, review, improve, or polish existing documentation." --- # Refine Doks (`refine-doks`) Read existing technical documentation and specifications in the project's configured documentation directory, check them against the Doks guidelines, and refine them with focused, surgical edits. ## Scope & Change Rules - **One File at a Time**: List all documentation files that need updating, then process **one file at a time** (unless the user explicitly instructs otherwise) and ask for confirmation before proceeding to the next file. - **Single-File Body Rule**: During each file pass, update the body content of **only that single target documentation file**. - **Cross-Reference Exception**: Modifying other documentation files during a pass is permitted **only** to add or update cross-references (such as linking a domain term to its `*.glossary.md` file, linking between `*.story.md` and `*.architecture.md` files, or fixing broken relative links). Do not rewrite, expand, or restructure the prose body of those secondary files. - **No Unapproved Detail Expansion**: If a refinement would add more detail to the document, explicitly confirm with the user before adding it. If the session is not interactive, prefer **not** to add detail—focus on conciseness, structure, terminology consistency, and cross-references instead. - **No Trivial Churn**: If the audit finds no significant issues, do not make changes just for the sake of editing. Announce that there are no changes to make and let the requester know they can ask for a more thorough pass or suggest specific changes. ## Documentation Guidelines Documentation under `/` (organized either flat or grouped into domain subfolders) must follow the [writing style guide](../../style.md) and adhere to the following standards: ### Document Types 1. **Glossary Files (`.glossary.md`)** - Defines a single domain or system term. - Follow the guidelines in [glossary.md](../../glossary.md) when writing or refining glossary files. 2. **User Story Files (`.story.md`)** - Describes an operation a user (or external actor) can perform on the system. - Follow the guidelines in [story.md](../../story.md) when writing or refining user story files. 3. **Architectural Documents (`.architecture.md`)** - Provides a high-level description of an aspect of the system. - Follow the guidelines in [architecture.md](../../architecture.md) when writing or refining architectural documents. ### Cross-Linking & Grounding Rules - **Once Per Section**: Link to a given glossary term, user story, architectural document, or code anchor at most once per section (on its first mention in that section). Do not repeat the same link on subsequent mentions within the same section, keeping cross-references accessible without cluttering the prose with link formatting. - **Glossary Links**: When a user story or architectural document references a defined domain term, link its first mention in each section to its corresponding `*.glossary.md` file using a relative Markdown link. - **Story <-> Architecture Links**: Cross-reference user stories (`*.story.md`) with the architectural documents (`*.architecture.md`) that implement them, and list supported user stories or key domain terms in architectural documents where relevant. - **Code Anchors**: Ground glossary definitions and architectural overviews with accurate links or paths to the actual source files, symbols, and tests in the repository. User stories must not reference code. ## Workflow 1. **Resolve Configuration (`./doks.yml`)** - Check the repository root for `./doks.yml` and read the `base-dir` property. - If `./doks.yml` does not exist or `base-dir` is not configured: 1. Ask the user which root directory they want to use for documentation (e.g., `docs`). 2. Create `./doks.yml` at the repository root with: ```yaml base-dir: ``` - Verify that `/` exists and contains documentation files to refine. 2. **Audit Existing Documentation via a Sub-Agent** - Do **not** scan or read all documentation files directly in the main agent, as doing so pollutes the main agent's context window. - Launch a read-only exploration sub-agent (e.g., using the `task` tool with `agent_type: "explore"`) and pass it: - The configured `` path. - Any specific target file or topic requested by the user (if provided). - A summary of the Document Types and Cross-Linking & Grounding Rules above. - Instruct the sub-agent to inspect `/` (`*.glossary.md`, `*.story.md`, `*.architecture.md`, and any index files) alongside relevant source files in the repository, and return **only**: 1. **Files Needing Updates**: The complete list of documentation file paths that need refinement, ordered by priority, with a brief summary of why each file needs updating. 2. **Findings Grouped by Change Type**: For each file needing updates, the specific guideline gaps or inaccuracies grouped by type of change (e.g., adding/updating cross-references, using glossary terms consistently, aligning document structure/sections, updating code anchors, tightening prose per the style guide). 3. **Cross-Reference Candidates**: Other existing documentation files that should be linked from each target file or that need cross-reference link updates pointing to it. 3. **List Files to Update and Plan the Current File** - If the audit finds no significant issues across the documentation (or in the requested target file), stop without modifying any files: announce that there are no changes to make, and tell the requester that they may ask to be more thorough or suggest specific changes. - Present the complete list of files that need updating to the user. - Unless the user explicitly asks to process multiple files at once, select the first (or next) target file to process one at a time. - In the main agent, read only the current target documentation file (and any relevant source code files needed to verify accuracy) along with the specific sections of candidate files that require cross-reference links. - If any proposed change would add more detail to the document, ask the user for confirmation before including it. If the session is not interactive, omit changes that add more detail. - If there are many changes for the current file spanning multiple categories, organize the planned edits into distinct groups by **type of change** (for example, *adding cross-references*, *using the same glossary term consistently*, *restructuring sections*, or *updating code anchors*). - Present the grouped plan for the current file and ask the user how they wish to proceed: 1. **Do everything in one go** 2. **Do each group of changes at a time (recommended)** - If the user chooses **do each group of changes at a time**, ask the user what the commit strategy is: 1. **Commit automatically**: After applying each group of changes, automatically stage and commit those changes before proceeding to the next group. 2. **Stop after making changes and wait for explicit approval**: After applying a group of changes, stop and wait for the user's explicit approval before proceeding to the next group. 4. **Refine the Current Target File and Advance** - Execute the changes for the current target file according to the user's chosen strategy (all at once, or group by group with the selected commit strategy). - **Update the Target File's Body**: - Bring the target file into full compliance with the [writing style guide](../../style.md) and its document type guidelines (`*.glossary.md`, `*.story.md`, or `*.architecture.md`). - Ensure all code anchors (file paths, symbols, types, tests) match the current codebase. - Add missing relative Markdown links from the target file to related glossary, user story, and architectural files. - **Update Cross-References in Other Files (If Needed)**: - In other documentation files, **only** add or update relative Markdown links / cross-references (for example, linking mentions of a glossary term or adding a link in a "Related Stories/Architecture" section). - Never modify or rewrite the body prose of any file other than the current single target file. - **Confirm Before Proceeding to the Next File**: - Once the current target file (and its cross-references) is complete, if additional files from the audit list still need updating, ask the user for confirmation before proceeding to the next file (repeating Steps 3–4 for that file).