--- title: "Workflow Documentation Audit Report" description: "> Conducted: 2026-02-02 > Scope: Workflow commands, command docs, guides, YAML definitions, and cross-references > Method: Full read of all files in scope, cross-referencing YAML definitions against docs" type: skill canonical_url: https://claudary.paisolsolutions.com/skills/audit-workflow-docs source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:08:03.042Z license: CC-BY-4.0 attribution: "Workflow Documentation Audit Report — Claudary (https://claudary.paisolsolutions.com/skills/audit-workflow-docs)" --- # Workflow Documentation Audit Report > Conducted: 2026-02-02 > Scope: Workflow commands, command docs, guides, YAML definitions, and cross-references > Method: Full read of all files in scope, cross-referencing YAML definitions against docs ## Overview # Workflow Documentation Audit Report > Conducted: 2026-02-02 > Scope: Workflow commands, command docs, guides, YAML definitions, and cross-references > Method: Full read of all files in scope, cross-referencing YAML definitions against docs --- ## Executive Summary The workflow documentation is unusually thorough for a project of this size. The `WORKFLOW_COMMANDS.md` file is a well-structured 876-line reference with mermaid diagrams, input/output tables, and checkpoint documentation. The `docs/workflow/` directory provides a clean separation between phase overviews and per-command descriptions, and the YAML definitions are consistent and well-typed. However, the documentation has grown organically across three layers (README, `WORKFLOW_COMMANDS.md`, and `docs/workflow/`) without clear delineation of audience or purpose. This creates significant redundancy, a confusing entry path for new users, and several structural mismatches between what the YAML definitions declare and what the docs describe. This report documents all findings, organizes them by area, and proposes a restructuring plan for migration to Astro + Starlight. --- ## 1. Per-Area Findings ### 1.1 `docs/WORKFLOW_COMMANDS.md` **Strengths:** - Comprehensive: covers all four phases with mermaid diagrams, command signatures, process steps, output sections, and publish locations. - The Document Flow Summary table (lines 87-97) is an excellent quick-reference artifact. - Checkpoint documentation (lines 740-812) is thorough and includes realistic examples with response types. - Workflow Variations section (lines 816-838) clearly communicates the three main paths through the system. **Weaknesses:** - **Drift from YAML manifest.** The document describes four phases (Discovery, Planning, Execution, Retrospectives) and nine commands. The YAML manifest defines five phases (Intake, Discovery, Planning, Execution, Retrospective) and twelve commands plus one utility. The entire Intake phase (3 commands) is absent from `WORKFLOW_COMMANDS.md`. - **Naming inconsistencies.** The document uses old command names (`create-epic-discovery`, `synthesize-discovery`, `approve-synthesis`, `create-epic-plan`, `create-implementation-plan`) while the YAML manifest uses shorter identifiers (`discovery:create`, `discovery:synthesize`, `discovery:approve`, `planning:epic-plan`, `planning:impl-plan`). A reader switching between the two sources will be confused about which name to use. - **`complete-sprint` is documented but absent from the manifest.** `WORKFLOW_COMMANDS.md` describes `complete-sprint` as a command (lines 632-673). The manifest's retrospective phase lists only `retrospectives:complete-epic`. There is a `commands/project/retrospectives/complete-sprint.md` implementation file but no `.yaml` definition file for it. This is either a manifest omission or the command was removed without updating the docs. - **Common Ground absent.** The manifest includes `common-ground` as a utility command. `WORKFLOW_COMMANDS.md` does not mention it at all, despite its relevance to the workflow (it can be invoked at any point). - **Monolithic structure.** At 876 lines, the file tries to be both a conceptual introduction and a complete reference. The mermaid diagrams and process descriptions serve a "getting started" reader, while the checkpoint tables and integration points serve a "deep reference" reader. These audiences need different documents. **Recommendations:** 1. Add the Intake phase to `WORKFLOW_COMMANDS.md` or explicitly state it is a pre-workflow phase documented elsewhere. 2. Resolve the command naming inconsistency: pick one canonical form (the YAML `command` identifier) and use it consistently, with aliases noted parenthetically. 3. Either add `complete-sprint` to the manifest YAML (with a `.yaml` definition file) or remove it from `WORKFLOW_COMMANDS.md`. 4. Add a brief mention of `common-ground` as a utility command available during any phase. 5. For the Astro site, split this into a conceptual overview page and individual command reference pages. --- ### 1.2 `docs/workflow/*.md` (Phase Overviews and Command Descriptions) **Strengths:** - Clean, consistent structure across all 18 files. Every phase overview has Purpose, Commands table, Outputs, Prerequisites, and Next Steps. Every command description has Overview, Inputs table, Outputs table, Prerequisites, and Next Steps. - Inputs and outputs match the YAML definitions exactly in all files reviewed. This is strong evidence of either co-generation or disciplined manual maintenance. - Next Steps sections create a navigable chain: each doc tells you where to go next, forming a complete user journey. - Status badges (`**Status:** Planned`) on intake commands clearly communicate availability. **Weaknesses:** - **No common-ground phase overview.** There is a `docs/workflow/common-ground.md` command description, but no phase overview that contextualizes it. The manifest lists it under `utilities:`, not under a phase. The doc structure treats it as though it belongs to a phase. - **No `complete-sprint` description.** There is no `docs/workflow/retrospective-complete-sprint.md`. The retrospective phase overview mentions only `complete-epic`. If `complete-sprint` is a valid command, it needs a description doc. - **Phase names are inconsistent.** The manifest uses `retrospective` (singular). `WORKFLOW_COMMANDS.md` uses `Retrospectives` (plural). The phase overview file is `retrospective-phase.md` (singular). The command prefix in the manifest is `retrospectives:complete-epic` (plural). This inconsistency will cause confusion in code, docs, and URL generation. - **Relative links may break in a docs site context.** All Next Steps links use relative paths like `[Planning Phase](planning-phase.md)`. These work within the `docs/workflow/` directory but will need transformation for a docs site with different URL structures. **Recommendations:** 1. Decide whether `complete-sprint` exists in the system. If yes, create `docs/workflow/retrospective-complete-sprint.md` and add it to the manifest. If no, remove all references. 2. Standardize singular vs. plural: the manifest phase name, the YAML command prefix, the docs directory name, and the file naming convention should all agree. 3. Treat `common-ground` as a standalone utility in the docs structure (not shoehorned into a phase pattern). --- ### 1.3 `docs/COMMON_GROUND.md` **Strengths:** - Exceptionally well-written conceptual documentation. The Background & Motivation section (lines 16-41) provides genuine insight into the design rationale. - The two-phase flow diagram (lines 69-88) clearly illustrates the interactive process. - The confidence tiers (ESTABLISHED, WORKING, OPEN) are well-defined with practical examples and behavior descriptions. - The use cases section (lines 328-372) maps real scenarios to specific command flags. **Weaknesses:** - **Typo on line 176.** "groundin file" should be "grounding file." - **Overlap with README.** The README (lines 182-227) duplicates the confidence tier explanation and the `--graph` mermaid example. When this content moves to a docs site, the README version should be a brief pointer. - **No link to the workflow docs.** The Related Documentation section links to `WORKFLOW_COMMANDS.md` and `ATLASSIAN_MCP_SETUP.md`, but does not link to the `docs/workflow/common-ground.md` command description or the YAML definition. A reader in the workflow mindset has no bridge from here to the workflow system. - **No link FROM workflow docs.** `WORKFLOW_COMMANDS.md` does not mention or link to `COMMON_GROUND.md` at all. The two documentation trees are disconnected. **Recommendations:** 1. Fix the "groundin file" typo. 2. Add a link to `docs/workflow/common-ground.md` in the Related Documentation section. 3. Add a link to `docs/COMMON_GROUND.md` from within `WORKFLOW_COMMANDS.md` (perhaps in a "Utility Commands" section). 4. For the Astro site, deduplicate the README and `COMMON_GROUND.md` versions of the confidence tier explanation. --- ### 1.4 `docs/ATLASSIAN_MCP_SETUP.md` **Strengths:** - Excellent task-oriented structure. A user can follow from top to bottom and end up with a working setup. - Covers both Cloud and Server/Data Center configurations. - The Quick Start Checklist (lines 453-461) is a useful verification artifact. - Security considerations are thorough: credential protection, read-only mode, space/project filtering, audit trail, and token revocation. - Environment variable reference tables (lines 421-449) serve as a quick lookup. **Weaknesses:** - **Only linked from README and COMMON_GROUND.md.** `WORKFLOW_COMMANDS.md` does not link to this guide despite requiring Atlassian integration for all non-intake commands. A user reading the workflow docs and encountering Jira/Confluence references has no pointer to setup instructions. - **Docker-only approach.** The guide assumes Docker. If a user cannot or does not want to run Docker, there is no alternative path (e.g., `npx` or `pip` installation of the MCP server). - **No version pinning guidance.** The guide uses `:latest` for the Docker image. For production workflows, this is risky. A note about pinning to a specific version would be prudent. **Recommendations:** 1. Add a link to `ATLASSIAN_MCP_SETUP.md` from the Integration Points section of `WORKFLOW_COMMANDS.md`. 2. Add a note about version pinning for the Docker image. 3. Mention alternatives to Docker if available, or explicitly state Docker is required. --- ### 1.5 `docs/local_skill_development.md` **Strengths:** - Solves a real problem clearly: how to test skill changes without releasing. - The symlink workflow is well-explained with exact commands. - Caveats section (lines 96-113) proactively addresses the most likely failure modes. - Quick Reference section (lines 132-149) provides copy-paste commands. **Weaknesses:** - **Orphaned document.** No other document in the project links to this file. It is not referenced from README.md, CONTRIBUTING.md, or any guide. A contributor who needs it will not find it through navigation. - **No mention of the workflow system.** The guide covers skill development but says nothing about developing or testing workflow commands. Given that commands have a parallel structure (YAML definitions, description docs, implementation `.md` files), a contributor working on workflow commands has no equivalent guide. - **Placeholder paths.** The guide uses ``, ``, `` as placeholders without providing a concrete example of what these look like for the claude-skills project specifically. **Recommendations:** 1. Link this file from CONTRIBUTING.md and README.md (Documentation section). 2. Add a section or separate document for workflow command development. 3. Include one concrete example with actual claude-skills paths alongside the generic placeholders. --- ### 1.6 `commands/workflow-manifest.yaml` **Strengths:** - Clean DAG structure with typed dependency strengths (`required` vs. `recommended`). - `optional: true` on discovery phase correctly models the skippable nature of that phase. - `external_skills` reference to `feature-forge` documents the cross-cutting dependency. - `run_once: true` on intake correctly distinguishes project-level from epic-level phases. **Weaknesses:** - **Missing `complete-sprint`.** The retrospective phase lists only `retrospectives:complete-epic`. The `complete-sprint` command exists as an implementation `.md` file but has no YAML definition and no manifest entry. This is the single largest manifest/docs mismatch. - **No YAML definition files for intake commands exist as `.md` implementation files.** The YAML `path` fields point to `commands/intake/document-codebase.md`, `commands/intake/capture-behavior.md`, and `commands/intake/create-system-description.md`. None of these files exist on disk. The YAML `status: planned` field signals this is expected, but the schema documentation says "`Must resolve to an existing file when status: existing`" -- so the `planned` status makes this valid. However, the schema doc does not explicitly state that `planned` status exempts the path resolution rule. - **Phase name mismatch.** The manifest uses `retrospective` (singular) but the command identifiers use `retrospectives:` (plural). **Recommendations:** 1. Resolve the `complete-sprint` question: add it to the manifest or remove the orphaned `.md` file. 2. Make the planned-status path exemption explicit in the schema documentation. 3. Align the phase name and command prefix (both singular or both plural). --- ### 1.7 Command YAML Definitions (Sample of 6) **Strengths:** - 100% schema compliance across all 12 files reviewed. Every file has `command`, `phase` (where applicable), `path`, `description`, `inputs`, `outputs`, `requires`, `status`, `argument-hint`, and `repeat`. - Input/output types are consistent and match the schema's allowed values. - The `description` field correctly points to the corresponding `docs/workflow/*.md` file in every case. - `requires` fields accurately distinguish commands needing ticketing/documentation backends from those that do not. **Weaknesses:** - **Intake commands point to non-existent implementation files.** `commands/intake/document-codebase.yaml` has `path: commands/intake/document-codebase.md` but this file does not exist. Same for the other two intake commands. The `status: planned` field explains this, but a CI validation step should catch it. - **`common-ground.yaml` has no `phase` field.** This is correct per the schema (utilities omit `phase`), but is inconsistent with the schema documentation which lists `phase` as required. The schema doc should explicitly state that `phase` is omitted for utility commands. **Recommendations:** 1. Add a CI validation that verifies `path` files exist when `status: existing`. 2. Clarify in the schema documentation that `phase` is omitted for utility commands. --- ## 2. Workflow Documentation Gap Analysis ### Commands Documented vs. Commands in YAML | Command | YAML Def | Manifest | `WORKFLOW_COMMANDS.md` | `docs/workflow/` desc | Implementation `.md` | |---------|----------|----------|------------------------|----------------------|---------------------| | `intake:document-codebase` | Yes | Yes | **NO** | Yes | **NO** (planned) | | `intake:capture-behavior` | Yes | Yes | **NO** | Yes | **NO** (planned) | | `intake:create-system-description` | Yes | Yes | **NO** | Yes | **NO** (planned) | | `discovery:create` | Yes | Yes | Yes | Yes | Yes | | `discovery:synthesize` | Yes | Yes | Yes | Yes | Yes | | `discovery:approve` | Yes | Yes | Yes | Yes | Yes | | `planning:epic-plan` | Yes | Yes | Yes | Yes | Yes | | `planning:impl-plan` | Yes | Yes | Yes | Yes | Yes | | `execution:execute-ticket` | Yes | Yes | Yes | Yes | Yes | | `execution:complete-ticket` | Yes | Yes | Yes | Yes | Yes | | `retrospectives:complete-epic` | Yes | Yes | Yes | Yes | Yes | | `retrospectives:complet --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/audit-workflow-docs) · https://claudary.paisolsolutions.com