wgordon17/code-quality

Interactive bug investigation workflow using background agents. Use when the user says "I'm going to report bugs", "let's hunt bugs", "investigate these issues", or describes wanting to report issues one-by-one while agents investigate in parallel. Also activates when the user reports a bug/issue and a BUGS.md file exists or was recently created.

Use when user needs multi-stakeholder analysis, business impact assessment, or wants perspectives from different roles. Triggers on: "analyze from business perspective", "what would stakeholders think", "impact analysis", "business case for", "ROI of"

Use when user requests deep research, comprehensive analysis, or thorough investigation of any topic. Triggers on: "research X thoroughly", "deep dive into", "comprehensive analysis of", "investigate X exhaustively", "compare X options", "evaluate alternatives for". Supports two modes: External (web research, current behavior) and Bridged (internal project investigation followed by external best-practices research).

Deep code quality audit system. Use when asked to: - "Audit the codebase" - "Find unused code" - "Check for duplicates" - "Validate library usage" - "Review the entire project" Analyzes files in parallel with LSP and Context7, detecting issues, duplicates, and documentation drift.

Comprehensive finding fixer. Use when asked to "fix these findings", "fix the review", "address the issues", or after running /pr-review, /plan-review, or /bug-investigation and wanting to act on the findings. Reads findings from the current session context, investigates each finding via background agents, and implements all fixes with the lead. Auto-detects fix target (plan file, code, bugs). For plan-review Research Gaps and Unknown Unknowns, runs actual spikes and verification — executes the research, not just documents it.

Incremental planning workflow that replaces native plan mode with issue tracking integration (GH issues, Jira cards). Use when Claude tries to enter plan mode (EnterPlanMode is denied by hook), when asked to "plan", "design an approach", "how should we implement", or before any multi-file implementation task. Asks clarifying questions first, writes plan to file incrementally with file structure mapping, BUGS.md cross-referencing (sets Tracked In for overlapping bug entries), per-task quality review (sonnet subagent), tiered breakpoints for scope vs detail ambiguity, and assumption surfacing in Phase 6. Provides research context and summaries in chat for feedback. Never displays full plan content in chat.

Generate a PROJECT_INDEX.md for token-efficient codebase orientation. Use when starting work on an unfamiliar repo, when agents need project context without reading the full codebase, or when asked to "index the repo", "create a project index", "map the codebase".

PROACTIVE skill - Use when navigating code, understanding symbol definitions, finding references, or exploring call hierarchies. Triggers include questions like "where is X defined", "what calls Y", "show usages of Z", or any code exploration task. Prefer LSP over grep for semantic navigation.

Parallelized workload processing with structured chunking, mapper agents, and reducer synthesis. Use for codebase-wide analysis, bulk transformations, and large file audits (20+ files).

Multi-agent plan review with independent fresh-context reviewers. Use when asked to "review plan", "review this plan", "plan review", or given a plan file path to review. Spawns 6 parallel specialized reviewers (feasibility, scope, dependencies, unknown unknowns, architect, security), verifies findings by re-reading the plan, and prints a structured terminal report. Designed for cross-session use: write a plan in session A, review in session B.

Multi-agent PR review with finding verification. Use when asked to "review PR", "review this PR", "code review", or given a PR URL to review. Spawns 6 parallel specialized reviewers (security, QA, performance, code quality, correctness, plan adherence), verifies findings by investigating source code, categorizes by type, and prints a structured report to the terminal. Never comments on GitHub PRs.

Use when about to claim ANY work is complete — code, research, planning, config, or general answers. Also after /swarm, /spawn, subagent-driven development, or any significant deliverable.

Mid-task self-reflection checkpoint using Serena metacognitive tools. Use when you need to pause and evaluate: "am I on track?", "have I gathered enough info?", "am I actually done?". Triggers on: completing a significant chunk of work, before claiming done, when feeling uncertain about direction, after a long sequence of tool calls, before making large code changes.

Stateful multi-plan phase sequencing, dependency analysis, and roadmap lifecycle management. Detects existing roadmaps and routes to update, cleanup, status/drift, or fresh creation. Use when coordinating multiple implementation plans into parallel/sequential workstreams, or when managing an existing roadmap. Trigger phrases: "roadmap", "sequence plans", "coordinate multiple plans", "plan execution order", "roadmap status", "roadmap cleanup", "update roadmap", "roadmap drift", or when 2+ plans need ordering.

Run competing implementations in parallel with isolated worktrees, then judge and select the best approach. Use when multiple viable approaches exist and "try both and compare" beats "guess and commit."

Distills project-memory artifacts and pull requests into concise human-readable summaries. Use when asked to "summarize", "what's the status of", "is this plan done", "audit this", "review the artifact", "archive this plan", "summarize this PR", "what does this PR do", "PR summary", or when pointing at a file in hack/plans/, hack/swarm/, hack/research/, hack/speculative/, hack/map-reduce/, hack/unfuck/, or hack/BUGS.md. Supports all 8 artifact-producing skill outputs plus GitHub PRs. For quick PR summaries (not deep code review). Cross-session: reads persisted artifacts and audits against current codebase state.

Full agent swarm for implementation tasks. Launches a pipelined team of 21+ specialized agents (Architect, Security Design Reviewer, Reduction Analyst, Implementer, Reviewer, Test-Writer, Test-Runner, Boundary Updater, Security, QA, Code-Reviewer, Performance, Plan Adherence, Fixer, Test Coverage Agent, Code-Simplifier, Docs, Docs Reviewer, Lessons Extractor, Verifier, BDD-Step-Writer) with structured JSON communication, Cynefin domain classification, audit trails, and early user checkpoint. Use when asked to "swarm this", "full team", "agent team", "full send", or when maximum rigor is needed on an implementation task. Auto-detects optional domain reviewers (UI, API, DB) from codebase analysis.

Use when user requests user-guided test plans, UAT validation, acceptance criteria definition, or user journey testing. Triggers on: "test plan", "user journey test", "UAT", "acceptance criteria", "manual test plan", "user-guided test", "validate from user perspective", "walk me through testing", "define what to test". Takes an implementation plan file as input and produces a test plan document with user personas, Given/When/Then scenarios, manual UAT steps, traceability matrix, and optional BDD .feature files. Annotates the input plan file so downstream skills (/swarm, /plan-review, /pr-review, /fix, /quality-gate) discover and consume the test plan automatically.

Efficient test execution patterns for pytest and pre-commit — sequential execution, targeted re-runs, and smart failure handling. Use when running pytest, pre-commit, or other test suites.

Comprehensive one-shot repo cleanup skill. This skill should be used when the user asks to "clean up the repo", "remove dead code", "de-AI-slop", "unfuck this codebase", "comprehensive cleanup", "remove unused code", "simplify the codebase", "fix code quality", "clean everything up", "audit the codebase", "fix tech debt", "remove duplicates", "unify the architecture", "security review and fix", or wants a thorough, automated cleanup of their entire repository. Launches a full agent swarm to discover issues, plan fixes, and implement changes autonomously. Combines custom static/semantic analysis with existing code-quality review, architecture, security, QA, and simplification agents into a unified cleanup workflow.

PROACTIVE skill. Use when executing Python or writing bash/shell scripts, Makefiles, CI/CD configs, or automation scripts that invoke Python or manage dependencies. Enforces uv CLI to replace all python/pip/python3 usage.