From e70f086b7e037f7f58d063e5f596383b7cea24aa Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 25 Nov 2025 23:48:58 +0800 Subject: [PATCH] refactor: Update file paths in documentation to use relative paths for consistency and clarity --- .../commands/workflow/review-module-cycle.md | 86 ++++++++++--------- .../commands/workflow/review-session-cycle.md | 52 +++-------- .../review-directory-specification.md | 12 +-- 3 files changed, 61 insertions(+), 89 deletions(-) diff --git a/.claude/commands/workflow/review-module-cycle.md b/.claude/commands/workflow/review-module-cycle.md index f52944d5..6b7c2e8c 100644 --- a/.claude/commands/workflow/review-module-cycle.md +++ b/.claude/commands/workflow/review-module-cycle.md @@ -60,6 +60,7 @@ Independent multi-dimensional code review orchestrator with **hybrid parallel-it - **ONLY command** for independent multi-dimensional module review - Manages: dimension coordination, aggregation, iteration control, progress tracking - Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode +- **⚠️ CRITICAL CONSTRAINT**: Orchestrator and agents MUST NOT read, write, or modify dashboard.html during review execution. Dashboard is generated ONCE at initialization and remains static for user interaction only. ## How It Works @@ -187,14 +188,22 @@ SlashCommand(command="/workflow:session:start --auto \"Code review for [target_p // Parse output const sessionId = output.match(/SESSION_ID: (WFS-[^\s]+)/)[1]; -// Validate session exists -Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`); ``` **Step 2: Path Resolution & Validation** +```bash +# Expand glob pattern to file list (relative paths from project root) +find . -path "./src/auth/**" -type f | sed 's|^\./||' + +# Validate files exist and are readable +for file in ${resolvedFiles[@]}; do + test -r "$file" || error "File not readable: $file" +done +``` - Parse and expand file patterns (glob support): `src/auth/**` → actual file list - Validation: Ensure all specified files exist and are readable -- Store resolved files as absolute paths (e.g., `D:\\project\\src\\auth\\service.ts`) +- Store as **relative paths** from project root (e.g., `src/auth/service.ts`) +- Agents construct absolute paths dynamically during execution **Step 3: Output Directory Setup** - Output directory: `.workflow/active/${sessionId}/.review/` @@ -209,10 +218,17 @@ Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`); - Progress tracking: Create `review-progress.json` for dashboard polling **Step 5: Dashboard Generation** -- Read template: `~/.claude/templates/review-cycle-dashboard.html` -- Replace placeholders: `{{SESSION_ID}}`, `{{REVIEW_TYPE}}`, `{{REVIEW_DIR}}` -- Write to: `${sessionDir}/.review/dashboard.html` -- Output path to user: `file://${absolutePath}/dashboard.html` +```bash +# Copy template and replace placeholders in one command +cat ~/.claude/templates/review-cycle-dashboard.html \ + | sed "s|{{SESSION_ID}}|${sessionId}|g" \ + | sed "s|{{REVIEW_TYPE}}|module|g" \ + | sed "s|{{REVIEW_DIR}}|${reviewDir}|g" \ + > ${sessionDir}/.review/dashboard.html + +# Output path to user +echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html" +``` **Step 6: TodoWrite Initialization** - Set up progress tracking with hierarchical structure @@ -302,38 +318,6 @@ Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`); 1. Deep-dive JSON with root cause, remediation plan, impact assessment 2. Analysis report with detailed recommendations -## Dashboard Generation - -### Mechanism - -Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/templates/review-cycle-dashboard.html`, replaces placeholders, writes to output directory. Dashboard polls `review-progress.json` every 5 seconds for real-time updates, then loads all dimension JSON files when `phase=complete`. - -**CRITICAL**: Dashboard MUST be generated in **Phase 1** to enable real-time progress monitoring throughout execution. - -### Phase 1 Steps - -1. **Read & Process Template** - ```javascript - const template = Read('~/.claude/templates/review-cycle-dashboard.html'); - const dashboard = template - .replace('{{SESSION_ID}}', `Module: ${pathPattern}`) - .replace('{{REVIEW_TYPE}}', 'module'); - Write(`${outputDir}/dashboard.html`, dashboard); - ``` - -2. **Auto-open in Browser** (optional) - ```javascript - Bash(`start ${dashboardPath}`); // Windows - Bash(`open ${dashboardPath}`); // macOS - Bash(`xdg-open ${dashboardPath}`); // Linux - ``` - -3. **Output Path to User** - ``` - 📊 Dashboard: file://${absolutePath}/dashboard.html - 🔄 Monitor progress in real-time (auto-refresh every 5s) - ``` - ## Reference ### CLI Tool Configuration @@ -397,9 +381,9 @@ Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/te "session_id": "WFS-auth-system", "target_pattern": "src/auth/**", "resolved_files": [ - "D:\\project\\src\\auth\\service.ts", - "D:\\project\\src\\auth\\validator.ts", - "D:\\project\\src\\auth\\middleware.ts" + "src/auth/service.ts", + "src/auth/validator.ts", + "src/auth/middleware.ts" ], "phase": "parallel|aggregate|iterate|complete", "current_iteration": 1, @@ -815,3 +799,21 @@ TodoWrite({ 7. **Resume Support**: Interrupted reviews can resume from last checkpoint 8. **Export Results**: Use dashboard export for external tracking tools +## Related Commands + +### Automated Fix Workflow +After completing a module review, use the dashboard to select findings and export them for automated fixing: + +```bash +# Step 1: Complete review (this command) +/workflow:review-module-cycle src/auth/** + +# Step 2: Open dashboard, select findings, and export +# Dashboard generates: fix-export-{timestamp}.json + +# Step 3: Run automated fixes +/workflow:review-fix .workflow/active/WFS-{session-id}/.review/fix-export-{timestamp}.json +``` + +See `/workflow:review-fix` for automated fixing with smart grouping, parallel execution, and test verification. + diff --git a/.claude/commands/workflow/review-session-cycle.md b/.claude/commands/workflow/review-session-cycle.md index dcf47944..46467858 100644 --- a/.claude/commands/workflow/review-session-cycle.md +++ b/.claude/commands/workflow/review-session-cycle.md @@ -204,10 +204,17 @@ git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u - Progress tracking: Create `review-progress.json` for dashboard polling **Step 6: Dashboard Generation** -- Read template: `~/.claude/templates/review-cycle-dashboard.html` -- Replace placeholders: `{{SESSION_ID}}`, `{{REVIEW_TYPE}}`, `{{REVIEW_DIR}}` -- Write to: `${sessionDir}/.review/dashboard.html` -- Output path to user: `file://${absolutePath}/dashboard.html` +```bash +# Copy template and replace placeholders in one command +cat ~/.claude/templates/review-cycle-dashboard.html \ + | sed "s|{{SESSION_ID}}|${sessionId}|g" \ + | sed "s|{{REVIEW_TYPE}}|session|g" \ + | sed "s|{{REVIEW_DIR}}|${reviewDir}|g" \ + > ${sessionDir}/.review/dashboard.html + +# Output path to user +echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html" +``` **Step 7: TodoWrite Initialization** - Set up progress tracking with hierarchical structure @@ -298,35 +305,6 @@ git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u 1. Deep-dive JSON with root cause, remediation plan, impact assessment 2. Analysis report with detailed recommendations -## Dashboard Generation - -### Mechanism - -Dashboard uses **static HTML + JSON polling**: reads template from `~/.claude/templates/review-cycle-dashboard.html`, replaces placeholders, writes to output directory. Dashboard polls `review-progress.json` every 5 seconds for real-time updates, then loads all dimension JSON files when `phase=complete`. - -**CRITICAL**: Dashboard MUST be generated in **Phase 1** to enable real-time progress monitoring throughout execution. - -### Phase 1 Steps - -1. **Read & Process Template** - ```javascript - const template = Read('~/.claude/templates/review-cycle-dashboard.html'); - const dashboard = template.replace('{{SESSION_ID}}', sessionId); - Write(`${outputDir}/dashboard.html`, dashboard); - ``` - -2. **Auto-open in Browser** (optional) - ```javascript - Bash(`start ${dashboardPath}`); // Windows - Bash(`open ${dashboardPath}`); // macOS - Bash(`xdg-open ${dashboardPath}`); // Linux - ``` - -3. **Output Path to User** - ``` - 📊 Dashboard: file://${absolutePath}/dashboard.html - 🔄 Monitor progress in real-time (auto-refresh every 5s) - ``` ### Features Summary @@ -901,11 +879,3 @@ After completing a review, use the dashboard to select findings and export them See `/workflow:review-fix` for automated fixing with smart grouping, parallel execution, and test verification. -### Independent Module Review -For reviewing specific modules without a workflow session: - -```bash -/workflow:review-module-cycle -``` - -This command provides the same 7-dimension analysis but targets specific files or directories. diff --git a/.claude/workflows/review-directory-specification.md b/.claude/workflows/review-directory-specification.md index 3408d93f..e62ed692 100644 --- a/.claude/workflows/review-directory-specification.md +++ b/.claude/workflows/review-directory-specification.md @@ -64,16 +64,16 @@ Unified directory structure for all review commands (session-based and module-ba "module_scope": { "target_pattern": "src/auth/**", "resolved_files": [ - "D:\\project\\src\\auth\\service.ts", - "D:\\project\\src\\auth\\validator.ts" + "src/auth/service.ts", + "src/auth/validator.ts" ], "file_count": 2 }, "session_scope": { "commit_range": "abc123..def456", "changed_files": [ - "D:\\project\\src\\auth\\service.ts", - "D:\\project\\src\\payment\\processor.ts" + "src/auth/service.ts", + "src/payment/processor.ts" ], "file_count": 2 } @@ -112,8 +112,8 @@ Unified directory structure for all review commands (session-based and module-ba "low": 8 }, "critical_files": [ - "D:\\project\\src\\auth\\service.ts", - "D:\\project\\src\\payment\\processor.ts" + "src/auth/service.ts", + "src/payment/processor.ts" ], "iterations": [ {