Workflow Review

Systematic audit of the development workflow infrastructure.

When to Use

• •Periodically (every few sessions or after major workflow changes)
• •When something feels wrong (a tool doesn't work as expected, outputs don't match docs)
• •After refactoring workflow components (tools, skills, hooks)

Workflow

1. Inventory

Discover all workflow components:

• •Tool scripts: tools/*.sh
• •Skills: .claude/skills/*/SKILL.md
• •Commands: .claude/commands/*.md
• •Hooks: .claude/settings.json → hooks section
• •Project instructions: CLAUDE.md
• •Spec docs referencing workflow: docs/hypersonic/**/*.md

2. Cross-Reference Check

For each component, verify:

• •References match reality: file paths, tool names, output formats mentioned in docs actually exist
• •Interfaces are consistent: what tool A produces matches what tool B expects to consume
• •Hook targets exist: scripts referenced in .claude/settings.json hooks are present and executable
• •No orphaned tools: every tool script is referenced somewhere (CLAUDE.md, skill, or command)
• •No orphaned references: every reference in docs points to an existing tool/file

3. Freshness Check

For each component, verify:

• •Content matches current design: no references to removed mechanisms (e.g., old annotation systems, removed intermediate files)
• •Terminology is consistent: same concepts use same names across all files
• •No contradictions: two files don't describe the same mechanism differently

4. Completeness Check

• •Every tool has documentation: at least a header comment explaining usage
• •Every skill has clear inputs/outputs: what triggers it, what it produces
• •Workflow has coverage: identify gaps where a process step has no tooling support

5. Document Purpose Check

Every document should have exactly ONE purpose:

Check for:

• •Mixed-purpose documents (e.g., spec + status tracking + workflow methodology in one file)
• •Documents without clear purpose classification
• •Content that belongs in a different purpose category

6. Source-of-Truth Chain Check

For each document, trace the information flow:

1. •What is the canonical source of this information? (spec, code, tool output?)
2. •Does a workflow skill generate this information dynamically? (/test-plan, /verify, /spec-review?)
3. •Is this document a static copy of information that has a dynamic source?

If the answer to 2 AND 3 is yes → the document is a candidate for deletion. Report as: REDUNDANT: {file} — static copy of {canonical source}, generated dynamically by {skill}

7. Changelog Check

Read .claude/workflow-changelog.md (if exists):

• •Are recent changes reflected in all affected files?
• •Are there TODO items that haven't been addressed?

Output Format

# Workflow Review Report

**Date**: YYYY-MM-DD HH:MM
**Components audited**: N tools, N skills, N commands

## Status

| Component | Status | Issues |
|-----------|--------|--------|
| tools/profile-hot-path.sh | OK | - |
| tools/check-hot-path.sh | WARN | stale comment on line 5 |
| ... | ... | ... |

## Cross-Reference Issues
1. **file_a.md:line** references `tool_x` which doesn't exist
2. **file_b.sh** produces `output.txt` but **file_c.md** expects `result.txt`

## Staleness Issues
1. **file.md:line** mentions removed mechanism X

## Gaps
1. No tooling for [workflow step]

## Recommendations
1. Fix: [specific action]
2. Consider: [improvement suggestion]

Principles

• •Read everything, assume nothing: don't trust that files are consistent — verify
• •Report, don't fix: this is an audit tool, not a repair tool. Report findings for human review.
• •Minimal friction: this review should be fast to run and easy to interpret