Testing & Debugging Skills

Use when you are working on a Go project following the agile-team-v2 workflow — features in .features/, sprints in .sprints/, strategic ADRs in .adrs/, tactical/strategic decisions log in .decisions/, global architecture in .architecture/ (VISION.md + ARCHITECTURE.md + CONVENTIONS.md + INTEGRATIONS.md). The architect absorbs the ex-scaffolder role: scaffolds Go contracts (signatures with panic(\"not implemented\") bodies), inlines // AC: + // TODO(impl- , ac- ) markers above each scaffolded body, and decides the mechanical: true|false flag in FEATURE.md frontmatter. The PM has two passes: passe 1 (FEATURE.md narrative — Why/Context/User journey/Out of scope/Open questions), passe 2 (inline // SCENARIO: + t.Skip(\"not implemented\") in business test skeletons within pmtestterritories, skipped if mechanical: true). The sprint-planner lists tasks by code marker in SPRINT.md (no separate TASK.md / TASK-red.md / TASK-green.md / SCAFFOLD.md / TASKS.md files — those v1 artifacts no longer exist). Spec isolation between red and green is preserved by discipline: red reads // AC: + // SCENARIO:, green reads // AC: + red's committed test assertions. There is one red agent and one green agent (no per-tier variants — anticipates bloc 3). Tactical DECISIONS authored by green during a sprint (under R2 strict rules) are surfaced in RETRO.md decisionstostatue: and statued by the architect at the start of the next sprint via a Wave 1 task. The reviewer runs three passes (DoD via scripts/check.sh, Scenarios narrative-vs-tests, Security checklist). The Human override section of REVIEW.md is human-only with strict 5-field format; security findings cannot be overridden without a Decision reference. Triggers: any Go file editing in this kind of project (must use go-surgeon — never generic Edit/Write/Read), sprint planning, feature breakdown, FEATURE.md / SPRINT.md / REVIEW.md / RETRO.md / DECISION-NNN-.md mentions, dispute files in .disputes/, any of the product-manager/architect/sprint-planner/red/green/e2e-tester/reviewer/bug-detective agents, Authored-By: commit trailer, the // AC: / // SCENARIO: / TODO(impl-...) markers, or any repository containing .features/ / .sprints/ / .adrs/ / .architecture/ / .decisions/ directories. Consult before planning a sprint, before starting any task, before writing a commit, before responding to a dispute, or whenever you need to know what artifact goes where. Detailed marker conventions and lifecycle live in markers skill. Decision-log format and R2/R6 rules live in the separate decisions-and-adrs skill (loaded by architect/green/sprint-planner only).

Use whenever you need clarifications, decisions, or preferences from the user before proceeding on a task. Instead of asking inline in chat, materialize the questions as a structured QCM markdown file in .questions/ at the project root. The user answers by editing the file (replacing [-] with [x] or [ ]). Trigger on any ambiguity, missing decision, technical choice, or "should I do A or B" moment — especially during planning, triage, or before sprint kickoff. Do NOT use for trivial confirmations or for questions the project context already answers.

Use when you create, write, modify, or statue an entry under .decisions/ or .adrs/, or when you need to know the difference between a tactical DECISION and a strategic ADR, the two-zone frontmatter format of DECISION-NNN-.md (zone author + zone review with revisit/reviewedby/reviewedat/outcome fields), the R2 strict rules under which green is allowed to author a tactical DECISION (scope=tactical, revisit=true at creation, necessary to unblock current task, DECISION-NNN referenced in code or commit message), or the R6 three-level defence around the Authored-By: commit trailer (pre-commit format, CI git-blame ↔ trailer cross-check, reviewer pass DoD sanity check). Also covers the architect's three statuing outcomes (confirm / reformulate / supersede) for tactical DECISIONS surfaced in RETRO.md decisionstostatue: from the previous sprint, and the strategic ADR format. Loaded only by architect (writes strategic, statues tactical, both ADRs and DECISIONS), green (writes tactical DECISIONS under R2), and sprint-planner (lists pending tactical DECISIONS in decisionstostatue: for next sprint's Wave 1 task). Other agents (PM, red, e2e-tester, reviewer, bug-detective) can read DECISION / ADR files without this skill — they just need the Relevant decisions section of FEATURE.md to know which apply to a feature.

Designs HTTP API endpoints - routes, request/response types, validation rules, error codes. Called by go-architect when the feature includes an API surface.

Designs implementation architecture following hexagonal patterns, produces TASKS.md and individual task-N.md files for the orchestrator to execute using red-green TDD.

Bootstraps a new Go project from scratch with hexagonal architecture, testcontainers, CI pipeline, and the full skill/agent suite installed. Use when starting a new project or microservice.

You MUST use this before starting any feature with go-pm. Explores user intent, alternative approaches, and domain design through Socratic questioning before locking a spec. Prevents building the wrong thing.

Use when encountering any bug, test failure, or unexpected behavior in Go code — before proposing fixes. Enforces root cause investigation through the hexagonal layers. Also use when go-fixer circuit breaker has fired and the root cause is still unclear.

Use when a feature pipeline is fully complete — all tasks green, all reviews passed, acceptance criteria met. Guides final verification, cleanup of .plan/ artifacts, and branch integration (merge, PR, or keep).

Fresh-perspective agent invoked by circuit breakers when another skill is stuck. Reads the error context and attempts to fix the problem without the bias of previous failed attempts.

Writes zero-downtime, reversible, batched data migrations tested with testcontainers. Use for backfills, data transforms, column splits, and schema-level data moves.

Strict product manager that interrogates the user about feature specifications, detects maturity gaps, delegates to go-architect once the spec is solid, and arbitrates spec disputes during implementation.

Decomposes a product specification into ordered features with dependencies, tracks progress, and drives sequential execution through the go-hexagonal pipeline. Use when building a full product from a spec document.

Safe refactoring agent. First documents all inbound surfaces (HTTP, gRPC, message queues, etc.), creates exhaustive e2e tests with testcontainers to lock behavior, then plans and executes the rewrite with type-level compatibility guarantees. Use when restructuring, rewriting, or migrating existing code.

Analyzes .feedback/ data across features to detect recurring…

Thin task runner that executes .plan/ /TASKS.md by dispatching subagents for each task. Validates green phases by running tests. Does not inline skill files — agents must have skills installed.

Creates all scaffolding files for a feature - stubs, interfaces, typed IDs, mocks, skipped tests - ensuring the project compiles and all tests pass or skip.

ALWAYS load when browsing or editing go project. Use this skill whenever you need to read, navigate, explore, or modify Go source code in a project that has go-surgeon installed (check for the binary or go-surgeon in go.mod). This includes adding, updating, or deleting functions, methods, structs, and interfaces; generating mocks; implementing interface stubs; generating test skeletons; manipulating struct tags; extracting interfaces from structs; and exploring codebase structure. Trigger this skill for ANY Go code editing task — even simple ones like "add a method" or "rename this function" — because go-surgeon produces deterministic, AST-correct results that avoid indentation errors, import issues, and context window waste. Also trigger when the user says "explore the codebase", "find symbol X", "show me the function", "list packages", or wants to understand Go project structure. Do NOT use generic text tools (cat, sed, grep, diff) for Go code editing when go-surgeon is available.

Use when the user wants to scaffold, bootstrap, or generate architectural components in a Go project that has go-surgeon installed with scaffolding templates (.surgeon-templates/ directory). This includes bootstrapping new projects, adding features, creating new domain entities, generating HTTP handlers, adding repositories, or any request involving project structure generation. Trigger when the user mentions "scaffold", "bootstrap", "generate feature", "add a new entity/handler/repository", "create project structure", "hexagonal architecture", "DDD setup", or asks to create multiple related files following a pattern. Also trigger when hints from a previous scaffold execution suggest running another scaffold command. Always check for available templates before improvising file creation — the templates encode best practices and produce contextual hints that guide the next steps.

Red phase TDD - writes failing unit tests, contract tests, and e2e API tests. Covers all test levels in a single pass. Never touches implementation code.

Open REEL Kanban board in a new terminal…

Use when you need the exact format, lifecycle, or strict rules for the agile-team-v2 code markers — // AC: + // TODO(impl- , ac- ) + panic(\"not implemented\") (inlined by the architect during scaffolding above each scaffolded function body that maps to an acceptance criterion) and // SCENARIO: + // TODO(impl- , scenario- ) + t.Skip(\"not implemented\") (inlined by the PM in passe 2 inside business test skeletons under pmtestterritories). Covers the strict marker format that check.sh enforces (kebab-case feature-slug, three-digit zero-padded NNN, exact ac- or scenario- prefix), the pmtestterritories glob block declared in .architecture/CONVENTIONS.md (where // SCENARIO: markers may live), the seven-step marker lifecycle (architect scaffolds → PM passe 2 → red → green → e2e-tester → reviewer pass 2 → TODO removed when feature done while // AC: stays as permanent record), and the marker-based task lookup procedure (grep -rn TODO(impl-...) to locate the scaffolded body or test skeleton — replaces v1 TASK.md/TASK-red.md/TASK-green.md/SCAFFOLD.md prose intermediaries). Loaded by every agent that touches markers in any way: architect (writes // AC:), PM (writes // SCENARIO:), red (locates AC and writes assertions), green (reads AC and removes TODO when done), e2e-tester (locates SCENARIO and writes e2e assertions), reviewer (Pass 2 verifies marker ↔ user-journey alignment), sprint-planner (lists tasks by code marker in SPRINT.md). Bug-detective is the only agent that does not load this skill — it reads // AC: from committed code post-mortem without needing the format spec.

Reference guide for mct (claude-mercato), a Git-based package manager for Claude agent and skill definitions. Use this skill whenever the user asks how to use mct, asks about mct commands, wants to install/update/search/export agents or skills, asks about markets, drift, sync, pinning, import/export, or any other mct workflow. Also trigger when the user is looking for skills or agents to add to their project, wants to find a skill for a specific task, asks "is there a skill for X", "find me a skill that does Y", "what skills are available", or wants to browse or discover available Claude skills and agents.

Use when classifying a feature's complexity (mechanical, standard, architectural), when deciding which pipeline shape applies to a given feature, when escalating a task to a higher complexity level during execution, or when reviewing classification accuracy at retro. Triggers on FEATURE.md DoR review, sprint planning, task escalation via dispute or blocker, and RETRO.md classification accuracy sections. The complexity classification is distinct from the mechanical: flag in FEATURE.md frontmatter — they answer different questions and live under different rules. Complexity drives pipeline shape (which phases run); the mechanical flag drives whether the PM does passe 2 (skipped if true). Both can be set independently. In v2 the agent tier system was simplified — there is one red agent and one green agent, no per-tier variants — so this skill no longer routes red/green models, only pipeline shape. Consult before setting a complexity field, before deciding whether to skip PM/architect/scaffolder phases, before downgrading a pipeline (forbidden), and when analyzing past sprints for routing calibration. Do NOT load this skill for routine implementation work — it is only needed at classification and routing decision points.