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 <plugin>, <name>, <version> 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