Debug and Fix

Systematically debug and fix failing tests, build errors, or runtime issues using aggressive parallelization at every phase.

DO NOT STOP UNTIL THE ISSUE IS FIXED AND TESTS PASS.

Arguments

• $ARGUMENTS - Test name, error message, or description of the issue

Phase 1: Reproduce and Gather Context

1.1 Detect the Stack

Detect the stack from the first manifest in this table's row order that exists at the repository root. <pm> is the package manager chosen by lockfile, as in the skills:build skill. Prefer the project's own scripts or Makefile targets when they exist. When tests run in Docker Compose (Appwrite), run the same command inside the service, for example docker compose exec <service> vendor/bin/phpunit --filter Name.

Manifest	Stack	Test all	Test one	Build	Lint	Format	Static analysis	Coverage
build.gradle.kts / build.gradle	Gradle	./gradlew test	./gradlew test --tests "*Name*"	./gradlew build	./gradlew spotlessCheck (or ktlintCheck)	./gradlew spotlessApply (or ktlintFormat)	./gradlew detekt	./gradlew koverReport
pom.xml	Maven	mvn test	mvn test -Dtest=Name	mvn package	configured plugin	mvn spotless:apply if configured	—	mvn jacoco:report if configured
composer.json	PHP	composer test	composer test -- --filter Name	composer install	composer lint	composer format	composer check (PHPStan)	vendor/bin/phpunit --coverage-text (PCOV/Xdebug)
package.json	Node	<pm> test	<pm> test -- -t "Name"	<pm> run build	<pm> run lint	<pm> run format / npx prettier --write .	<pm> exec tsc --noEmit	<pm> test -- --coverage
Cargo.toml	Rust	cargo test	cargo test name	cargo build	cargo clippy -- -D warnings	cargo fmt	cargo clippy -- -D warnings	cargo llvm-cov if installed
go.mod	Go	go test ./...	go test -run Name ./...	go build ./...	go vet ./...	gofmt -w .	golangci-lint run if configured	go test -cover ./...
pyproject.toml / setup.py	Python	pytest	pytest -k name	pip install -e .	ruff check .	ruff format .	mypy . if configured	pytest --cov

Commands in this skill name a column of this table, for example "the stack's Test one command". Give every agent the detected stack's commands.

1.2 Gather Context in Parallel

Launch three parallel agents simultaneously to maximize information gathering speed.

Agent 1 - Reproduce the failure:

• Test failure: run the failing test ($ARGUMENTS) with the stack's Verbose single test command from Debug Techniques, or the Test all command to find every failure.
• Build error: run the stack's Build command and capture the complete error output, with stack traces enabled.
• Runtime error: get the full stack trace and identify the failing component.

Capture all error details: full error message, stack trace, test name and class, file and line number, input that caused the failure.

Agent 2 - Check recent changes:

git diff HEAD~5 --name-only
git diff HEAD~5 -- <relevant paths>

Identify what files changed recently that could be related to the failure. Summarize which changes are most likely to have introduced the bug.

Agent 3 - Check git history:

git log --oneline -15
git log --oneline -5 -- <files related to $ARGUMENTS>

Determine if this is a regression by finding when the relevant code last changed and who changed it.

Wait for all three agents to complete. Synthesize their findings to determine:

• Is this a single test failure or multiple?
• Is it flaky (intermittent)?
• Is it a regression (worked before)?
• What is the scope of the problem?

Phase 2: Root Cause Analysis

Using the error details from Phase 1, launch three parallel agents to analyze all relevant code simultaneously.

Agent 1 - Analyze the failing test (use Explore or read directly):

Read and understand the failing test file completely. Document:

• What the test expects
• What setup and mocks it uses
• What assertions are failing and why
• Whether the test itself is correct or buggy

Agent 2 - Analyze the code under test (use Explore or read directly):

Read the production code that the test exercises. Document:

• The relevant function or method signatures
• The control flow path that leads to the failure
• Any recent changes to this code (cross-reference with Phase 1 Agent 2 results)
• Potential bugs: null references, wrong logic, missing error handling, race conditions

Agent 3 - Analyze related dependencies (use Explore or read directly):

Read related files: interfaces, shared utilities, configuration, DI modules, database schemas, or mocks that the code under test depends on. Document:

• Whether any dependencies changed recently
• Whether mocks match current interfaces
• Whether configuration or DI wiring is correct
• Whether database state assumptions still hold

Wait for all three agents to complete. Synthesize their findings into a root cause hypothesis:

• What is wrong
• Why it causes this specific error
• What the minimal fix should be

Phase 3: Fix and Verify

3.1 Implement Fix

Use architect to implement the fix:

• Fix the root cause, not symptoms
• Make the minimal targeted change
• Preserve existing behavior for passing cases
• Do not change unrelated code

3.2 Parallel Verification

After implementing the fix, launch two parallel agents to verify simultaneously.

Agent 1 - Run the specific failing test:

Run the stack's Test one command for the failing test. Confirm the original failure is resolved. If it still fails, report the new error details.

Agent 2 - Run related tests:

Run the stack's Class, file or module command from Debug Techniques for the code the fix touched. Confirm no closely related tests have broken as a side effect of the fix.

Wait for both agents to complete. If either agent reports a failure, return to Phase 2 with the new information and repeat. Do not proceed until both pass.

Phase 4: Full Validation

Launch two parallel agents for final validation.

Agent 1 - Code review (use reviewer):

Review the fix for:

• Correctness: is this the right fix for the root cause?
• Edge cases: does it handle all boundary conditions?
• Side effects: could it cause other issues?
• Quality: does it follow project conventions and naming standards?

If the review finds issues, fix them before proceeding.

Agent 2 - Full test suite:

Run the stack's Test all and Build commands to catch any regressions anywhere in the codebase.

Wait for both agents to complete. If the full suite has failures, fix every one of them (there are no "pre-existing" failures). If the code review raised issues, address them and re-run verification.

4.1 Add Test Coverage

If the bug was not caught by existing tests:

• Add a test for this specific case
• Add tests for related edge cases
• Ensure this bug cannot recur

Run the new tests with the stack's Test one command to confirm they pass.

4.2 Commit Fix

Delegate to the skills:commit command:

Skill(skill="skills:commit", args="fix(<scope>): [description of what was fixed]")

Debug Techniques

Each stack's form for one test with its full output, for a whole class, file or module, and for rerunning a flaky test without a cached result:

Stack	Verbose single test	Class, file or module	Flaky rerun
Gradle	./gradlew test --tests "*Name*" --info	./gradlew :module:test --tests "com.example.NameTest"	./gradlew cleanTest test --tests "*Name*"
Maven	mvn test -Dtest=Name -DtrimStackTrace=false	mvn test -pl module -Dtest=NameTest	mvn test -Dtest=Name
PHP	composer test -- --filter Name	composer test -- tests/Path/NameTest.php	composer test -- --filter Name
Node	<pm> test -- -t "Name"	<pm> test -- path/to/name.test.ts	<pm> test -- -t "Name"
Rust	RUST_BACKTRACE=1 cargo test name -- --nocapture	cargo test -p crate module::	cargo test name
Go	go test -run Name -v ./...	go test -v ./path/to/package	go test -run Name -count=1 ./...
Python	pytest -k name -vv -l	pytest tests/test_name.py::TestName	pytest -k name

For Test Failures

Run the failing test alone with the stack's Verbose single test command, then widen to its class, file or module.

For Null Pointer / Missing Data

• Check test setup and mocks
• Verify DI is configured correctly
• Check database state for integration tests

For Async / Timing Issues

• Check the lifetimes and cancellation of coroutines, tasks and promises
• Look for race conditions
• Verify test uses proper async testing utilities

For Flaky Tests

Run the stack's Flaky rerun command ten times and stop at the first failure:

for run in $(seq 1 10); do <flaky rerun command> || { echo "Failed on run $run"; break; }; done

Test Failure Policy

IMPORTANT: There is no such thing as a "pre-existing" test failure. If any test fails, whether it appears related to your changes or not, you must fix it. The task always completes with completely passing tests.

Completion Criteria

• Root cause identified
• Fix implemented
• Original failing test passes
• ALL tests pass (no exceptions for "pre-existing" failures)
• No regressions introduced
• Fix reviewed via reviewer
• Committed with clear message