Michael Czechowski
fc24f9a8ab
ADR, changelog, code-review, debug, doc-sync, explain, feature, hotfix, improve, onboard, plan, prototype, refactor, security-scan, smoke-test, speckit-flow, supervise, test-gen, and more. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
128 lines
4.1 KiB
YAML
128 lines
4.1 KiB
YAML
kind: WavePipeline
|
|
metadata:
|
|
name: explain
|
|
description: "Deep-dive explanation of code, modules, or architectural patterns"
|
|
release: true
|
|
|
|
input:
|
|
source: cli
|
|
example: "explain the pipeline execution system and how steps are scheduled"
|
|
|
|
steps:
|
|
- id: explore
|
|
persona: navigator
|
|
workspace:
|
|
mount:
|
|
- source: ./
|
|
target: /project
|
|
mode: readonly
|
|
exec:
|
|
type: prompt
|
|
source: |
|
|
Explore the codebase to understand: {{ input }}
|
|
|
|
## Exploration Steps
|
|
|
|
1. **Find relevant files**: Use Glob and Grep to locate all files related
|
|
to the topic. Cast a wide net — include implementations, tests, configs,
|
|
and documentation.
|
|
|
|
2. **Trace the call graph**: For key entry points, follow the execution flow.
|
|
Note which functions call which, and how data flows through the system.
|
|
|
|
3. **Identify key abstractions**: Find the core types, interfaces, and structs.
|
|
Note their responsibilities and relationships.
|
|
|
|
4. **Map dependencies**: Which packages/modules does this depend on?
|
|
Which depend on it?
|
|
|
|
5. **Find tests**: Locate test files that exercise this code.
|
|
Tests often reveal intended behavior and edge cases.
|
|
|
|
6. **Check configuration**: Find config files, constants, or environment
|
|
variables that affect behavior.
|
|
|
|
output_artifacts:
|
|
- name: exploration
|
|
path: .wave/output/exploration.json
|
|
type: json
|
|
handover:
|
|
contract:
|
|
type: json_schema
|
|
source: .wave/output/exploration.json
|
|
schema_path: .wave/contracts/explain-exploration.schema.json
|
|
on_failure: retry
|
|
max_retries: 2
|
|
|
|
- id: analyze
|
|
persona: planner
|
|
dependencies: [explore]
|
|
memory:
|
|
inject_artifacts:
|
|
- step: explore
|
|
artifact: exploration
|
|
as: codebase_map
|
|
workspace:
|
|
mount:
|
|
- source: ./
|
|
target: /project
|
|
mode: readonly
|
|
exec:
|
|
type: prompt
|
|
source: |
|
|
Analyze the architecture and design of the explored code.
|
|
|
|
Review the injected exploration data, then read the key source files identified. Focus on:
|
|
|
|
1. **Design patterns**: What patterns are used and why?
|
|
2. **Data flow**: How does data enter, transform, and exit?
|
|
3. **Error handling**: What's the error strategy?
|
|
4. **Concurrency model**: Goroutines, channels, mutexes?
|
|
5. **Extension points**: Where can new functionality be added?
|
|
6. **Design decisions**: What trade-offs were made?
|
|
output_artifacts:
|
|
- name: analysis
|
|
path: .wave/output/analysis.json
|
|
type: json
|
|
handover:
|
|
contract:
|
|
type: json_schema
|
|
source: .wave/output/analysis.json
|
|
schema_path: .wave/contracts/explain-analysis.schema.json
|
|
on_failure: retry
|
|
max_retries: 2
|
|
|
|
- id: document
|
|
persona: philosopher
|
|
dependencies: [analyze]
|
|
memory:
|
|
inject_artifacts:
|
|
- step: explore
|
|
artifact: exploration
|
|
as: codebase_map
|
|
- step: analyze
|
|
artifact: analysis
|
|
as: architecture
|
|
exec:
|
|
type: prompt
|
|
source: |
|
|
Write a comprehensive explanation document.
|
|
|
|
Review the injected exploration and architecture data, then produce a markdown document with:
|
|
|
|
1. **Overview** — One paragraph summary
|
|
2. **Key Concepts** — Core abstractions and terminology (glossary)
|
|
3. **Architecture** — How pieces fit together (include ASCII diagram)
|
|
4. **How It Works** — Step-by-step main execution flow with file:line refs
|
|
5. **Design Decisions** — Decision → Rationale → Trade-off entries
|
|
6. **Extension Guide** — How to add new functionality
|
|
7. **Testing Strategy** — How the code is tested
|
|
8. **Common Pitfalls** — Things that trip people up
|
|
|
|
Write for an experienced developer new to this codebase.
|
|
Use real file paths, function names, and type names.
|
|
output_artifacts:
|
|
- name: explanation
|
|
path: .wave/output/explanation.md
|
|
type: markdown
|