mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-11 17:21:03 +08:00
Add roles for fixer, reproducer, tester, verifier, and supervisor with detailed workflows
- Introduced `fixer` role for implementing code fixes based on RCA reports, including phases for parsing RCA, planning fixes, implementing changes, and documenting results. - Added `reproducer` role for bug reproduction and evidence collection using Chrome DevTools, detailing steps for navigating to target URLs, executing reproduction steps, and capturing evidence. - Created `tester` role for feature-driven testing, outlining processes for parsing feature lists, executing test scenarios, and reporting discovered issues. - Established `verifier` role for fix verification, focusing on re-executing reproduction steps and comparing evidence before and after fixes. - Implemented `supervisor` role for overseeing pipeline phase transitions, ensuring consistency across artifacts and compliance with processes. - Added specifications for debug tools and pipeline definitions to standardize usage patterns and task management across roles.
This commit is contained in:
catlog22
218
.claude/commands/ddd/doc-refresh.md
Normal file
218
.claude/commands/ddd/doc-refresh.md
Normal file
@@ -0,0 +1,218 @@
|
||||
---
|
||||
name: doc-refresh
|
||||
description: Incrementally update affected documents based on changed components/features. Layer 3 → 2 → 1 selective refresh. Called by sync/update or used standalone.
|
||||
argument-hint: "[-y|--yes] [--components <id1,id2,...>] [--features <id1,id2,...>] [--minimal] [--dry-run]"
|
||||
allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-update affected documents without confirmation prompts.
|
||||
|
||||
# DDD Doc Refresh Command (/ddd:doc-refresh)
|
||||
|
||||
## Purpose
|
||||
|
||||
Incrementally update **only the affected documents** after code changes. Unlike `/ddd:doc-generate` (full generation), this command selectively refreshes documents for specific components and features.
|
||||
|
||||
```
|
||||
affected component/feature IDs → update tech-registry (L3) → update feature-maps (L2) → update indexes (L1)
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
| Scenario | Use |
|
||||
|----------|-----|
|
||||
| After `/ddd:sync` detects code changes | **doc-refresh** (auto-called by sync) |
|
||||
| After `/ddd:update` traces impact | **doc-refresh** (auto-called by update) |
|
||||
| Manual refresh of specific component docs | **doc-refresh --components tech-auth-service** |
|
||||
| Quick metadata-only update | **doc-refresh --minimal --components tech-auth-service** |
|
||||
| Preview what would change | **doc-refresh --dry-run --components tech-auth-service** |
|
||||
|
||||
## Prerequisite
|
||||
|
||||
- `doc-index.json` must exist at `.workflow/.doc-index/doc-index.json`
|
||||
- At least one of `--components` or `--features` must be provided (or received from caller)
|
||||
- Corresponding documents must already exist (generated by `/ddd:doc-generate`)
|
||||
- If documents missing → error: "Documents not found. Run /ddd:doc-generate first."
|
||||
|
||||
## Phase 1: Determine Refresh Scope
|
||||
|
||||
### 1.1 Resolve Affected Entities
|
||||
|
||||
```
|
||||
IF --components provided:
|
||||
affected_components = parse comma-separated IDs
|
||||
affected_features = lookup featureIds for each component in doc-index.json
|
||||
|
||||
IF --features provided:
|
||||
affected_features = parse comma-separated IDs
|
||||
affected_components = union of all component IDs linked to features
|
||||
|
||||
Merge both sets if both flags provided.
|
||||
```
|
||||
|
||||
### 1.2 Validate Entities Exist
|
||||
|
||||
For each ID, verify it exists in doc-index.json. Warn and skip missing IDs.
|
||||
|
||||
### 1.3 Check Document Existence
|
||||
|
||||
For each affected entity, check if corresponding .md file exists:
|
||||
- Missing Layer 3 doc → warn: "Component doc not found. Run /ddd:doc-generate first."
|
||||
- Missing Layer 2 doc → warn: "Feature doc not found. Run /ddd:doc-generate first."
|
||||
|
||||
## Phase 2: Layer 3 — Update Component Docs
|
||||
|
||||
For each affected component's `tech-registry/{slug}.md`:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Update component documentation for {component.name} after code changes
|
||||
TASK:
|
||||
• Update code locations and line ranges
|
||||
• Update symbol list (add new exports, remove deleted)
|
||||
• Add change entry to history table
|
||||
• Refresh usage examples if API changed
|
||||
MODE: write
|
||||
CONTEXT: @{component.codeLocations[].path}
|
||||
EXPECTED: Updated markdown with current API state
|
||||
CONSTRAINTS: Preserve existing structure | Only update changed sections
|
||||
" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/
|
||||
```
|
||||
|
||||
Update frontmatter:
|
||||
```markdown
|
||||
---
|
||||
layer: 3
|
||||
component_id: tech-auth-service
|
||||
generated_at: {original}
|
||||
last_updated: ISO8601
|
||||
---
|
||||
```
|
||||
|
||||
### 2.1 Minimal Mode (--minimal)
|
||||
|
||||
With `--minimal`, only update:
|
||||
- `codeLocations` in frontmatter
|
||||
- `last_updated` timestamp
|
||||
- Skip CLI call for content regeneration
|
||||
|
||||
## Phase 3: Layer 2 — Update Feature Docs
|
||||
|
||||
For each affected feature's `feature-maps/{slug}.md`:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Update feature documentation for {feature.name} after component changes
|
||||
TASK:
|
||||
• Update component list if new components added
|
||||
• Update status if requirements now fully implemented
|
||||
• Add change entry to history table
|
||||
• Refresh integration guide if component APIs changed
|
||||
MODE: write
|
||||
CONTEXT: @.workflow/.doc-index/tech-registry/{affected-components}.md
|
||||
EXPECTED: Updated markdown reflecting current feature state
|
||||
CONSTRAINTS: Reference updated Layer 3 docs | Preserve business language
|
||||
" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/
|
||||
```
|
||||
|
||||
Update frontmatter:
|
||||
```markdown
|
||||
---
|
||||
layer: 2
|
||||
feature_id: feat-auth
|
||||
depends_on_layer3: [tech-auth-service, tech-user-model]
|
||||
generated_at: {original}
|
||||
last_updated: ISO8601
|
||||
---
|
||||
```
|
||||
|
||||
### 3.1 Minimal Mode (--minimal)
|
||||
|
||||
With `--minimal`, only update:
|
||||
- Component list in frontmatter
|
||||
- Feature status (if requirements mapping changed)
|
||||
- `last_updated` timestamp
|
||||
- Skip CLI call for content regeneration
|
||||
|
||||
## Phase 4: Layer 1 — Update Index Docs (conditional)
|
||||
|
||||
### 4.1 Trigger Conditions
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| New component registered | Update `tech-registry/_index.md` |
|
||||
| Component removed | Update `tech-registry/_index.md` |
|
||||
| Feature status changed | Update `feature-maps/_index.md` |
|
||||
| New feature added | Update `feature-maps/_index.md` + README.md |
|
||||
| Major architecture change | Update ARCHITECTURE.md |
|
||||
| New action-log entry | Update `action-logs/_index.md` |
|
||||
|
||||
### 4.2 Update _index.md Files
|
||||
|
||||
Refresh table entries for affected features/components:
|
||||
- `feature-maps/_index.md`
|
||||
- `tech-registry/_index.md`
|
||||
- `action-logs/_index.md` (if new action entry)
|
||||
|
||||
### 4.3 Update Overview Docs (only if significant)
|
||||
|
||||
If new features added or major status changes:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Update project overview docs after feature changes
|
||||
TASK:
|
||||
• Update README.md feature list
|
||||
• Update ARCHITECTURE.md if new components added
|
||||
• Update sessions/_index.md with new planning sessions
|
||||
MODE: write
|
||||
CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
|
||||
EXPECTED: Updated overview docs with current project state
|
||||
CONSTRAINTS: High-level only | Link to Layer 2 for details
|
||||
" --tool gemini --mode write --cd .workflow/.doc-index/
|
||||
```
|
||||
|
||||
### 4.4 Skip Layer 1
|
||||
|
||||
With `--minimal` or when changes are minor (only code location updates): skip Layer 1 entirely.
|
||||
|
||||
## Phase 5: Refresh Report
|
||||
|
||||
```
|
||||
Document Refresh Report
|
||||
|
||||
Affected Scope:
|
||||
Components: {N} ({component IDs})
|
||||
Features: {N} ({feature IDs})
|
||||
|
||||
Updated:
|
||||
Layer 3 (Components): {N} documents refreshed
|
||||
Layer 2 (Features): {N} documents refreshed
|
||||
Layer 1 (Indexes): {N} documents refreshed (or "skipped")
|
||||
|
||||
Mode: {full|minimal}
|
||||
```
|
||||
|
||||
## Dry-Run Mode
|
||||
|
||||
With `--dry-run`:
|
||||
- Execute Phase 1 (scope determination)
|
||||
- Display what would be updated (affected files list)
|
||||
- Skip all file writes (Phase 2-4)
|
||||
- Output: "Dry-run complete. {N} documents would be refreshed."
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `-y, --yes` | Auto-confirm all updates |
|
||||
| `--components <ids>` | Comma-separated component IDs to refresh |
|
||||
| `--features <ids>` | Comma-separated feature IDs to refresh |
|
||||
| `--minimal` | Only update metadata/frontmatter, skip content regeneration |
|
||||
| `--dry-run` | Preview what would change without modifying files |
|
||||
|
||||
## Integration Points
|
||||
|
||||
- **Input from**: `doc-index.json`, affected entity IDs (from `/ddd:sync` or `/ddd:update`)
|
||||
- **Called by**: `/ddd:sync` (after change detection + index update), `/ddd:update` (after impact tracing + index update)
|
||||
- **Standalone**: Can be run independently to refresh specific component/feature docs
|
||||
- **Prerequisite**: Documents must exist (generated by `/ddd:doc-generate`)
|
||||
Reference in New Issue
Block a user