--- name: best-of description: This skill should be used when the user asks to "compare code", "compare worktrees", "compare solutions", "which solution is better", "compare branches", "best of", "diff worktrees", "evaluate solutions", "pick the better implementation", "compare implementations", "review both solutions", or wants a structured, criteria-driven comparison of code across two git worktrees. Also triggered by the /best-of command. argument-hint: " [focus area or file path]" user-invocable: true --- # Code Comparison Compare two git worktrees side-by-side against software engineering best practices and project contribution guidelines. Produce a structured, evidence-based verdict on which solution is better and why. ## Task $ARGUMENTS ## Workflow ### Step 1: Parse Inputs and Validate Worktrees Extract the two worktree paths from the arguments. If an optional focus area or file path is provided, note it for scoped analysis. ```bash # Validate both paths are git worktrees or repositories git -C rev-parse --show-toplevel git -C rev-parse --show-toplevel ``` If either path is invalid, report the error and stop. If only one path or no path is provided, ask the user for the missing worktree path(s) using the AskUserQuestion tool. Identify the worktrees: - **Worktree A**: first path argument - **Worktree B**: second path argument Run a quick orientation in both: ```bash # For each worktree git -C log --oneline -5 git -C branch --show-current git -C show --stat --oneline -1 # last commit's scope ``` If the two worktrees share a common ancestor (same repo, different branches), compute the divergence: ```bash MERGE_BASE=$(git -C merge-base HEAD $(git -C rev-parse HEAD)) git -C diff --stat $MERGE_BASE HEAD git -C diff --stat $MERGE_BASE HEAD ``` ### Step 2: Discover Project Guidelines Search **both** worktrees for contribution and convention files. Collect every rule that applies. Files to search for (using Glob in each worktree root): - `CLAUDE.md`, `AGENTS.md`, `**/CLAUDE.md`, `**/AGENTS.md` - `CONTRIBUTING.md`, `CONTRIBUTING.rst` - `.editorconfig` - Linter configs: `.eslintrc*`, `.prettierrc*`, `pyproject.toml`, `setup.cfg`, `.flake8`, `.rubocop.yml`, `biome.json`, `deno.json` - CI configs: `.github/workflows/*.{yml,yaml}`, `Makefile`, `Taskfile.yml`, `justfile` - `package.json` (scripts and lint config sections), `Cargo.toml`, `go.mod`, `tsconfig.json` Read each file found. Extract every actionable rule, convention, or constraint. Compile them into a **Project Rules Checklist** — one line per rule, with the source file and its directory scope referenced (e.g. rules from `src/backend/CLAUDE.md` apply only to files under `src/backend/`). Root-level files apply globally. When evaluating compliance in Step 5, only apply each rule to files within its scope. If the two worktrees have different guideline files, note the differences — this itself is a finding. ### Step 3: Identify the Comparison Surface Determine which files to compare. Use one of these strategies depending on context: **Strategy A — Common ancestor diff** (preferred when worktrees share history): ```bash # Files changed in A since divergence git -C diff --name-only $MERGE_BASE HEAD # Files changed in B since divergence git -C diff --name-only $MERGE_BASE HEAD ``` **Strategy B — Direct diff** (when worktrees are independent): ```bash diff -rq --exclude='.git' | head -200 ``` If the output reaches exactly 200 lines, warn the user that the file list was truncated and suggest narrowing the comparison scope with a focus area argument. **Strategy C — Focused** (when user specified a file or directory): Compare only the specified path(s) across both worktrees. Build the **File Comparison Manifest** — a list of file pairs to compare, categorized: - Files modified in both (direct comparison) - Files only in A (unique to A's approach) - Files only in B (unique to B's approach) - Files identical in both (skip these) ### Step 4: Deep Analysis — Parallel Agents Dispatch **three** parallel agents (Agent tool, subagent_type: "general-purpose"). All three run in a single message. Each agent receives the File Comparison Manifest and the Project Rules Checklist from Step 2. **Agent 1 — Correctness & Logic** > "You are reviewing two code solutions side by side. Read the following files from both worktrees and evaluate: > 1. **Correctness**: Does each solution produce correct results? Check edge cases, error paths, race conditions, off-by-one errors. > 2. **Error handling**: Are errors caught at boundaries, propagated meaningfully, not swallowed? > 3. **Type safety**: Are types precise? Are escape hatches (any, Object, void*) minimized? > 4. **Security**: Check OWASP top 10 — injection, XSS, path traversal, secrets in code. > > For each criterion, state which worktree is stronger and cite specific file:line evidence. > > Worktree A: > Worktree B: > Files to compare: > Project rules: " **Agent 2 — Design & Architecture** > "You are reviewing two code solutions side by side. Read the following files from both worktrees and evaluate: > 1. **Readability & clarity**: Names, control flow, comments, formatting. > 2. **DRY**: Duplication, reuse of existing utilities. > 3. **SOLID principles**: Single responsibility, open/closed, dependency inversion — applied pragmatically. > 4. **Separation of concerns**: Business logic vs I/O vs presentation. > 5. **Complexity**: Cyclomatic complexity, nesting depth, cognitive load. > 6. **API & interface design**: Function signatures, public surface area, consistency. > > For each criterion, state which worktree is stronger and cite specific file:line evidence. > > Worktree A: > Worktree B: > Files to compare: > Project rules: " **Agent 3 — Practices, Testing & Compliance** > "You are reviewing two code solutions side by side. Read the following files from both worktrees and evaluate: > 1. **Testing**: Coverage, test quality, edge case tests, alignment with project test patterns. > 2. **Naming & conventions**: Adherence to project naming conventions found in linter configs and contribution docs. > 3. **Git hygiene**: Commit atomicity, message quality, minimal diff, no debug artifacts. > 4. **Performance**: Unnecessary allocations, algorithmic complexity, appropriate data structures. > 5. **Project guideline compliance**: Check every rule in the Project Rules Checklist below. Flag each violation with the rule and source file. > > For each criterion, state which worktree is stronger and cite specific file:line evidence. > > Worktree A: > Worktree B: > Files to compare: > Project rules: " ### Step 5: Synthesize and Score Collect findings from all three agents. For each of the 15 evaluation criteria (see `references/evaluation-criteria.md`), assign a score (1-5) to each worktree based on agent findings: | # | Criterion | Worktree A | Worktree B | Notes | |---|-----------|:----------:|:----------:|-------| | 1 | Correctness | | | | | 2 | Readability & Clarity | | | | | 3 | DRY | | | | | 4 | SOLID Principles | | | | | 5 | Error Handling | | | | | 6 | Security | | | | | 7 | Testing | | | | | 8 | Performance | | | | | 9 | Naming & Conventions | | | | | 10 | Separation of Concerns | | | | | 11 | Complexity | | | | | 12 | Type Safety | | | | | 13 | API & Interface Design | | | | | 14 | Git Hygiene | | | | | 15 | Project Guideline Compliance | | | | Compute the totals. Do NOT use a simple sum as the verdict — weigh correctness and security higher than naming and git hygiene. Use this weighting: | Weight | Criteria | |--------|----------| | **3x** | Correctness, Security | | **2x** | Error Handling, Testing, Project Guideline Compliance | | **1x** | All others | ### Step 6: Present the Verdict Present to the user with this structure: ``` ## Code Comparison: Worktree A vs Worktree B ### Summary <2-3 sentence verdict: which solution is better overall and the primary reasons why> ### Scorecard ### Weighted Totals - **Worktree A**: / - **Worktree B**: / ### Key Differentiators #### Where A is Stronger - : #### Where B is Stronger - : ### Project Guideline Violations ### Recommendations ``` End by asking: **"Would you like me to go deeper on any specific criterion, or apply the best parts of both solutions into a combined implementation?"** ## Constraints - **Read-only**: Do NOT modify any files in either worktree. This is a review, not an implementation. - **Evidence-based**: Every claim must cite a specific file:line from one of the worktrees. No vague assertions. - **Fair**: Do not favor one worktree over the other by default. Let the evidence decide. - **Proportional**: Scale depth to the size of the diff. A 5-line change doesn't need 15 criteria analyzed in depth — focus on what matters. A 500-line change warrants thorough analysis across all criteria. - **No phantom references**: Every file:line citation must be verified against the actual code. - **Project-aware**: The Project Rules Checklist from Step 2 is mandatory. Compliance with project guidelines is not optional. ## Additional Resources See `references/evaluation-criteria.md` (bundled with this skill) for detailed scoring guidance and criteria definitions.