# Grimblaz Agent Orchestra Documentation Finalization > - Skill: `tomevault-io/grimblaz-agent-orchestra-documentation-finalization` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/grimblaz-agent-orchestra-documentation-finalization` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/grimblaz-agent-orchestra-documentation-finalization/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/grimblaz-agent-orchestra-documentation-finalization --- # Documentation Finalization Reusable documentation-finalization process for implementation and design updates. ## When to Use - When implementation changed names, behavior, file paths, or architecture references in docs - When a design document in `Documents/Design/` must be created or updated for the current domain - When obsolete placeholders, duplicate guidance, or stale references must be removed before completion - When documentation work needs a consistent finalization checklist rather than ad hoc edits ## Purpose Make documentation reflect the shipped state of the repository. Treat deletion of stale content as first-class work, and verify every technical statement against implementation before leaving the documentation phase. ## Documentation Areas ### Development Docs - Update current-state, setup, architecture, and workflow documents to match the implementation - Replace outdated file paths, names, timelines, and phase markers - Remove "not yet implemented" language once behavior exists ### Design Docs - Keep terminology aligned with actual classes, methods, scripts, headings, and behaviors - Refresh examples, formulas, schemas, and interaction descriptions to match current behavior - Remove placeholders such as `TBD`, `coming soon`, or obsolete alternative designs ### Decision Docs - Update existing ADRs when a shipped decision changed - Create or refine decision records only when implementation introduced or documented an actual decision - Remove obsolete decision records only when a newer source of truth fully supersedes them ### Domain Design Docs - Prefer updating an existing domain file when the feature extends an established design area - Create a new `Documents/Design/{domain-slug}.md` file only when no current domain doc covers the feature area - Keep domain docs focused on the current design state, not as per-issue changelogs ## Documentation Maintenance Responsibilities The documentation specialist is responsible for maintaining: - **CHANGELOG.md**: Update BEFORE merge - add entry during PR documentation finalization. - **NEXT-STEPS.md**: Update BEFORE merge - update priorities during PR finalization. - **QUICK-START.md**: Update when tooling or setup instructions change. - **Documents/Decisions/**: Create new decision records from issue body design content during the implementation phase - keep existing ADRs accurate. - **ROADMAP.md**: Update when present - reflect milestone and priority changes from implemented features. See also: [Experience-Owner](../../agents/Experience-Owner.agent.md) for customer framing documentation. ## Finalization Workflow 1. Review the relevant implementation and determine what actually changed. 2. Update the affected development and design documents to match shipped behavior. 3. Apply any required decision-record updates tied to real implementation decisions. 4. Remove obsolete content, duplicate guidance, and placeholder text. 5. Verify terminology, file paths, cross-references, and examples against the codebase. 6. Run markdown formatting and repo validation before handing off completion. ## Quality Checks - Match code names, signatures, entity names, and workflow labels exactly - Verify file paths, section cross-references, and command examples still exist - Remove stale future-tense statements once the work shipped - Prefer consolidation over duplication when multiple docs describe the same rule - For domain design docs, describe the stable domain behavior rather than issue-by-issue history ## Conciseness Guidelines - Target roughly 150-250 lines per permanent document when practical - Split a document when it serves multiple unrelated purposes or becomes hard to navigate - Prefer linking to the authoritative doc instead of restating the same guidance in multiple places - Value deletion as much as addition when reducing confusion ## Validation - Run `markdownlint-cli2 --fix "**/*.md"` - Run `pwsh -NoProfile -NonInteractive -File .github/scripts/quick-validate.ps1` - When agent markdown is edited, confirm the `tools:` frontmatter still matches the capabilities described in the body ## Gotchas | Trigger | Gotcha | Fix | | ----------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- | | Updating docs from intent instead of code | Documentation drifts toward the plan rather than the shipped state | Verify names, paths, and behavior against the current implementation | | Trigger | Gotcha | Fix | | -------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- | | Turning a domain design doc into issue notes | The file becomes a changelog and stops reflecting the current UX | Rewrite the doc around current domain behavior and delete drift | ## Frame Ports Filled By This Skill | Port | Work adapter | Auto-N/A adapter | Explicit-skip adapter | | --- | --- | --- | --- | | `implement-docs` | [agents/Doc-Keeper.agent.md](../../agents/Doc-Keeper.agent.md); [adapters/implement-docs-adapter.md](adapters/implement-docs-adapter.md) | [adapters/implement-docs-auto-na-adapter.md](adapters/implement-docs-auto-na-adapter.md) | [adapters/implement-docs-explicit-skip-adapter.md](adapters/implement-docs-explicit-skip-adapter.md) | In `/spine-run`, the `implement-docs` port resolves through [adapters/implement-docs-adapter.md](adapters/implement-docs-adapter.md) as the work adapter executed by Senior Engineer. Hub-flow dispatch uses `agents/Doc-Keeper.agent.md` directly. This split-declaration state is documented in [Documents/Design/frame-architecture.md](../../Documents/Design/frame-architecture.md); see footnote § (split-declaration #612). --- > Source: [Grimblaz/agent-orchestra](https://github.com/Grimblaz/agent-orchestra) — distributed by [TomeVault](https://tomevault.io).