the-rabak/workflows-review

Goal

Run an exhaustive, multi-agent review of branch or document changes, synthesize the findings, and create todo files immediately.

Use this skill when

• A branch, diff, file path, or current changes need deep review.
• You need parallel specialist reviews, stakeholder analysis, and scenario exploration.
• Findings must be converted into todos/ artifacts for follow-up work.

Do not use this skill when

• The request is implementation, not review.
• The repository or baseline is not ready for review because required context or failing quality gates still need to be addressed.
• The user wants to triage existing todos rather than create new review findings; use triage.

Non-negotiable rules

• Determine the exact review target first: branch, markdown file, or current branch.
• Read compound-engineering.local.md; if it does not exist, run setup before continuing.
• Treat docs/plans/*.md and docs/solutions/*.md as protected artifacts. Never recommend deleting, removing, or gitignoring them. Discard any finding that does.
• If tests or linting are already failing for the review target, surface that immediately instead of pretending the review is clean.
• You must run all configured review agents in parallel.
• You must always run agent-native-reviewer and learnings-researcher in parallel with the configured agents.
• Run conditional migration and deployment agents only when the changed files or commit context justify them.
• Run code-simplicity-reviewer as part of the review.
• After synthesis, create all todo files immediately. Do not ask for approval first.
• Todo creation must run in parallel via the file-todos skill or equivalent batched todo creation flow.

Procedure

Execute the full source-of-truth workflow below. Preserve every conditional branch, phase, checklist, and validation step from the original instructions. When the workflow says to ask, wait, route, or run in parallel, do that exactly.

Arguments

[branch name, file path, or empty for current branch]

Review Command

Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection.

Introduction

Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance

Prerequisites

• Git repository
• Clean main/master branch (for diff baseline)
• Proper permissions to create worktrees and access the repository
• For document reviews: Path to a markdown file or document

Main Tasks

1. Determine Review Target & Setup (ALWAYS FIRST)

#$ARGUMENTS

First, I need to determine the review target type and set up the code for analysis.

Immediate Actions:

• [ ] Determine review type: branch name, file path (.md), or empty (current branch)
• [ ] Check current git branch
• [ ] Determine the default branch:

  default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
  [ -z "$default_branch" ] && default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
  

• [ ] If ALREADY on the target branch -> proceed with analysis
• [ ] If DIFFERENT branch -> offer to use worktree: "Use git-worktree skill for isolated analysis" or git checkout [branch]
• [ ] Get the list of changed files:

  git diff --name-only ${default_branch}...HEAD
  

• [ ] Get the full diff for review:

  git diff ${default_branch}...HEAD
  

• [ ] Get commit messages for context:

  git log --oneline ${default_branch}..HEAD
  

• [ ] Set up language-specific analysis tools
• [ ] Prepare security scanning environment

Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.

Protected Artifacts

The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:

• docs/plans/*.md -- Plan files created by /workflows-plan. These are living documents that track implementation progress (checkboxes are checked off by /workflows-work).
• docs/solutions/*.md -- Solution documents created during the pipeline.

If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.

Load Review Agents

Read compound-engineering.local.md in the project root. If found, use review_agents from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.

If no settings file exists, invoke the setup skill to create one. Then read the newly created file and continue.

Parallel Agents to review the branch changes:

Run all configured review agents in parallel using Task tool. For each agent in the review_agents list:

Task {agent-name}(branch diff content + review context from settings body)

Additionally, always run these regardless of settings:

• Use the agent-native-reviewer skill to: branch diff content - Verify new features are agent-accessible
• Use the learnings-researcher skill to: branch diff content - Search docs/solutions/ for past issues related to this PR's modules and patterns

Conditional Agents (Run if applicable):

These agents are run ONLY when the branch changes match specific criteria. Check the changed files list to determine if they apply:

MIGRATIONS: If PR contains database migrations or data backfills:

• Use the data-integrity-guardian skill to: branch diff content - Reviews migration safety, constraint naming, and migration conventions
• Use the data-migration-expert skill to: branch diff content - Validates ID mappings match production, checks for swapped values, verifies rollback safety
• Use the deployment-verification-agent skill to: branch diff content - Creates Go/No-Go deployment checklist with SQL verification queries

When to run:

• Changed files include database/migrations/*.php
• Changes modify columns that store IDs, enums, or mappings
• Changes include data backfill scripts or artisan commands
• Commit messages mention: migration, backfill, data transformation, ID mapping

What these agents check:

• data-integrity-guardian: Reviews migration safety, project conventions (separate files for table/indexes/FKs, constraint naming with unq_/fk_/idx_ prefixes)
• data-migration-expert: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
• deployment-verification-agent: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, Horizon monitoring plans

4. Ultra-Thinking Deep Dive Phases

For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.

Complete system context map with component interactions

Phase 3: Stakeholder Perspective Analysis

ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points?

1. Developer Perspective

   • How easy is this to understand and modify?
   • Are the APIs intuitive?
   • Is debugging straightforward?
   • Can I test this easily?

2. Operations Perspective

   • How do I deploy this safely?
   • What metrics and logs are available?
   • How do I troubleshoot issues?
   • What are the resource requirements?

3. End User Perspective

   • Is the feature intuitive?
   • Are error messages helpful?
   • Is performance acceptable?
   • Does it solve my problem?

4. Security Team Perspective

   • What's the attack surface?
   • Are there compliance requirements?
   • How is data protected?
   • What are the audit capabilities?

5. Business Perspective

   • What's the ROI?
   • Are there legal/compliance risks?
   • How does this affect time-to-market?
   • What's the total cost of ownership?

Phase 4: Scenario Exploration

ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress?

• [ ] Happy Path: Normal operation with valid inputs
• [ ] Invalid Inputs: Null, empty, malformed data
• [ ] Boundary Conditions: Min/max values, empty collections
• [ ] Concurrent Access: Race conditions, deadlocks
• [ ] Scale Testing: 10x, 100x, 1000x normal load
• [ ] Network Issues: Timeouts, partial failures
• [ ] Resource Exhaustion: Memory, disk, connections
• [ ] Security Attacks: Injection, overflow, DoS
• [ ] Data Corruption: Partial writes, inconsistency
• [ ] Cascading Failures: Downstream service issues

6. Multi-Angle Review Perspectives

Technical Excellence Angle

• Code craftsmanship evaluation
• Engineering best practices
• Technical documentation quality
• Tooling and automation assessment

Business Value Angle

• Feature completeness validation
• Performance impact on users
• Cost-benefit analysis
• Time-to-market considerations

Risk Management Angle

• Security risk assessment
• Operational risk evaluation
• Compliance risk verification
• Technical debt accumulation

Team Dynamics Angle

• Code review etiquette
• Knowledge sharing effectiveness
• Collaboration patterns
• Mentoring opportunities

4. Simplification and Minimalism Review

Run the Task code-simplicity-reviewer() to see if we can simplify the code.

5. Findings Synthesis and Todo Creation Using file-todos Skill

ALL findings MUST be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis - do NOT present findings for user approval first. Use the skill for structured todo management.

Step 1: Synthesize All Findings

Consolidate all agent reports into a categorized list of findings. Remove duplicates, prioritize by severity and impact.

• [ ] Collect findings from all parallel agents
• [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
• [ ] Discard any findings that recommend deleting or gitignoring files in docs/plans/ or docs/solutions/ (see Protected Artifacts above)
• [ ] Categorize by type: security, performance, architecture, quality, etc.
• [ ] Assign severity levels: CRITICAL (P1), IMPORTANT (P2), NICE-TO-HAVE (P3)
• [ ] Remove duplicate or overlapping findings
• [ ] Estimate effort for each finding (Small/Medium/Large)

Step 2: Create Todo Files Using file-todos Skill

Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user.

Implementation Options:

Option A: Direct File Creation (Fast)

• Create todo files directly using Write tool
• All findings in parallel for speed
• Use standard template from .github/skills/file-todos/assets/todo-template.md
• Follow naming convention: {issue_id}-pending-{priority}-{description}.md

Option B: Sub-Agents in Parallel (Recommended for Scale) For large PRs with 15+ findings, use sub-agents to create finding files in parallel:

# Launch multiple finding-creator agents in parallel
Task() - Create todos for first finding
Task() - Create todos for second finding
Task() - Create todos for third finding
etc. for each finding.

Sub-agents can:

• Process multiple findings simultaneously
• Write detailed todo files with all sections filled
• Organize findings by severity
• Create comprehensive Proposed Solutions
• Add acceptance criteria and work logs
• Complete much faster than sequential processing

Execution Strategy:

1. Synthesize all findings into categories (P1/P2/P3)
2. Group findings by severity
3. Launch 3 parallel sub-agents (one per severity level)
4. Each sub-agent creates its batch of todos using the file-todos skill
5. Consolidate results and present summary

Process (Using file-todos Skill):

1. For each finding:

   • Determine severity (P1/P2/P3)
   • Write detailed Problem Statement and Findings
   • Create 2-3 Proposed Solutions with pros/cons/effort/risk
   • Estimate effort (Small/Medium/Large)
   • Add acceptance criteria and work log

2. Use file-todos skill for structured todo management:

   skill: file-todos
   

   The skill provides:

   • Template location: .github/skills/file-todos/assets/todo-template.md
   • Naming convention: {issue_id}-{status}-{priority}-{description}.md
   • YAML frontmatter structure: status, priority, issue_id, tags, dependencies
   • All required sections: Problem Statement, Findings, Solutions, etc.

3. Create todo files in parallel:

   {next_id}-pending-{priority}-{description}.md
   

4. Examples:

   001-pending-p1-path-traversal-vulnerability.md
   002-pending-p1-api-response-validation.md
   003-pending-p2-concurrency-limit.md
   004-pending-p3-unused-parameter.md
   

5. Follow template structure from file-todos skill: .github/skills/file-todos/assets/todo-template.md

Todo File Structure (from template):

Each todo must include:

• YAML frontmatter: status, priority, issue_id, tags, dependencies
• Problem Statement: What's broken/missing, why it matters
• Findings: Discoveries from agents with evidence/location
• Proposed Solutions: 2-3 options, each with pros/cons/effort/risk
• Recommended Action: (Filled during triage, leave blank initially)
• Technical Details: Affected files, components, database changes
• Acceptance Criteria: Testable checklist items
• Work Log: Dated record with actions and learnings
• Resources: Links to PR, issues, documentation, similar patterns

File naming convention:

{issue_id}-{status}-{priority}-{description}.md

Examples:
- 001-pending-p1-security-vulnerability.md
- 002-pending-p2-performance-optimization.md
- 003-pending-p3-code-cleanup.md

Status values:

• pending - New findings, needs triage/decision
• ready - Approved by manager, ready to work
• complete - Work finished

Priority values:

• p1 - Critical (blocks merge, security/data issues)
• p2 - Important (should fix, architectural/performance)
• p3 - Nice-to-have (enhancements, cleanup)

Tagging: Always add code-review tag, plus: security, performance, architecture, laravel, vue, quality, etc.

Step 3: Summary Report

After creating all todo files, present comprehensive summary:

##  Code Review Complete

**Review Target:** Branch `[branch-name]` (vs `[default-branch]`)

### Findings Summary:

- **Total Findings:** [X]
- ** CRITICAL (P1):** [count] - BLOCKS MERGE
- ** IMPORTANT (P2):** [count] - Should Fix
- ** NICE-TO-HAVE (P3):** [count] - Enhancements

### Created Todo Files:

**P1 - Critical (BLOCKS MERGE):**

- `001-pending-p1-{finding}.md` - {description}
- `002-pending-p1-{finding}.md` - {description}

**P2 - Important:**

- `003-pending-p2-{finding}.md` - {description}
- `004-pending-p2-{finding}.md` - {description}

**P3 - Nice-to-Have:**

- `005-pending-p3-{finding}.md` - {description}

### Review Agents Used:

- rabak-laravel-reviewer
- rabak-vue-reviewer
- security-sentinel
- performance-oracle
- architecture-strategist
- agent-native-reviewer
- [other agents]

### Next Steps:

1. **Address P1 Findings**: CRITICAL - must be fixed before merge

   - Review each P1 todo in detail
   - Implement fixes or request exemption
   - Verify fixes before merging PR

2. **Triage All Todos**:
   ```bash
   ls todos/*-pending-*.md  # View all pending todos
   /triage                  # Use slash command for interactive triage
   ```

3. Work on Approved Todos:

   /resolve_todo_parallel  # Fix all approved items efficiently
   

4. Track Progress:

   • Rename file when status changes: pending -> ready -> complete
   • Update Work Log as you work
   • Commit todos: git add todos/ && git commit -m "refactor: add code review findings"

Severity Breakdown:

** P1 (Critical - Blocks Merge):**

• Security vulnerabilities
• Data corruption risks
• Breaking changes
• Critical architectural issues

** P2 (Important - Should Fix):**

• Performance issues
• Significant architectural concerns
• Major code quality problems
• Reliability issues

** P3 (Nice-to-Have):**

• Minor improvements
• Code cleanup
• Optimization opportunities
• Documentation updates

### 7. End-to-End Testing (Optional)

After presenting the Summary Report, offer browser testing:

```markdown
**"Want to run browser tests on the affected pages?"**
1. Yes - run `/test-browser`
2. No - skip

If User Accepts Testing:

Spawn a subagent to run browser tests (preserves main context):

Use the general-purpose skill to: "Run /test-browser for the current branch. Test all affected pages, check for console errors, handle failures by creating todos and fixing."

The subagent will:

1. Identify pages affected by the PR
2. Navigate to each page and capture snapshots (using agent-browser CLI)
3. Check for console errors
4. Test critical interactions
5. Pause for human verification on OAuth/email/payment flows
6. Create P1 todos for any failures
7. Fix and retry until all tests pass

Standalone: /test-browser

Important: P1 Findings Block Merge

Any ** P1 (CRITICAL)** findings must be addressed before merging. Present these prominently and ensure they're resolved before the MR is accepted.

## Required output
Return a review summary that includes:
- Review target and default-branch comparison.
- Total findings with P1, P2, and P3 breakdown.
- Created todo file paths.
- Review agents used, including any conditional agents.
- Any protected-artifact findings that were discarded.
- Recommended next steps.