---
name: nurture
description: This skill should be used when the user asks to "nurture", "review and fix", "improve code quality", "add tests", "fix remaining bugs", "polish the implementation", "check for completeness", or invokes "/brains:nurture". Reviews implementation for completeness, then fixes issues including bugs, missing features, and lack of tests. Supports --single (default), --parallel, and --debate modes for the review phase. When invoked by a phase-3 teammate with --scope phase-N, scopes the review to changes in that plan-phase, commits code and updates .gitignore, reflects any half-complete state in docs, and files follow-up beads tasks for the next phase or cleanup.
user-invocable: true
argument-hint: "[--single|--parallel|--debate] [--scope phase-N | all] [paths...]"
allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent
---

# Nurture: Review, Test, and Refine

Review an implementation for completeness and quality, then systematically fix issues. Focus on bugs from incomplete code, missing features, lack of verifiable end-to-end tests, and other quality problems.

Set the plugin base path:
```bash
BRAINS_PATH="<base directory from header>/../.."
```

## Mode Behavior

Modes apply to the **review** phase. Fixing always happens locally.

| Mode | Flow |
|------|------|
| `--single` | Local LLM reviews independently. **(default)** |
| `--parallel` | Review locally, then send to council for additional review. |
| `--debate` | Multi-round review deliberation across LLMs. |

For `--parallel` and `--debate`, read and follow `$BRAINS_PATH/references/multi-llm-protocol.md`. Under `--lean`, read the compact excerpt at `$BRAINS_PATH/references/multi-llm-protocol-compact.md` instead; consult the full file only for debate-round synthesis or error handling.

## Scope

The `--scope` flag controls what nurture reviews:

- `--scope phase-N` — review only files touched in the current plan-phase (use `git log --since` or the teammate's known commit range). File follow-up beads tasks labelled `brains:phase-<N+1>` if a next phase exists, else `brains:cleanup`. Invoked by phase-3 teammates.
- `--scope all` (default when invoked standalone) — review all recent changes per the classic behavior.

## Process

### 1. Gather Context

Identify what to review:

- **BRAINS outputs**: Check `docs/research/` for research docs (legacy fallback: `docs/plans/`), `docs/adr/` for ADRs, and `docs/plans/` for map/implement specs
- **Recent changes**: `git log --oneline -20` and `git diff main...HEAD --stat` to scope what was built
- **User scope**: If the user specified a scope, focus on those files/modules
- **Test coverage**: Check for existing test files, coverage reports

### 2. Conduct Review

Evaluate the implementation against these criteria:

**Completeness:**
- Does the code implement everything in the design spec?
- Are there TODO comments, placeholder implementations, or stub functions?
- Are all planned features present and functional?

**Correctness:**
- Are there logic errors or off-by-one mistakes?
- Do edge cases get handled?
- Does error handling follow the design spec?

**Test coverage:**
- Do end-to-end tests exist that verify the user-facing behavior?
- Are critical paths tested?
- Can the tests be run and do they pass?

**Code quality:**
- Does the code follow existing project patterns and conventions?
- Are there unnecessary abstractions or missing necessary ones?
- Is the code readable without excessive comments?

**Integration:**
- Does the new code integrate cleanly with existing code?
- Are interfaces respected?
- Are there breaking changes to existing functionality?

**Documentation (per ADR-005 reqs 24-26):**
- Are user-facing docs (README, CHANGELOG, ADRs) updated to reflect the changes in this scope?
- Are new flags, options, or commands documented in README's flag reference?
- Does CHANGELOG.md have an entry for any user-visible behavior change?

### 3. Council Review (if multi-LLM mode)

**Parallel mode:** After local review, send findings plus the code to the council:

```
Review this implementation for [project].

[Design spec summary]
[Files changed — list paths]

Focus on:
1. Bugs or logic errors
2. Missing features relative to the design spec
3. Test coverage gaps — especially missing E2E tests
4. Integration issues with existing code
5. Code quality concerns
```

Use `star-chamber review` (not `ask`) for code-focused review. Pass the changed files as review targets.

**Debate mode:** Run multi-round code review deliberation. Each round focuses on a different aspect (correctness, completeness, quality).

### 4. Compile Issue List

Consolidate all findings into a prioritized list:

| Priority | Category | Issue | File(s) | Fix |
|----------|----------|-------|---------|-----|
| P0 | Bug | [description] | [files] | [approach] |
| P1 | Missing feature | [description] | [files] | [approach] |
| P1 | Missing test | [description] | [files] | [approach] |
| P1 | Missing docs | [description] | [files] | [approach] |
| P2 | Code quality | [description] | [files] | [approach] |

Present the list to the user. Get approval before fixing.

## Commit and .gitignore responsibilities (phase-3 teammate scope only)

When invoked with `--scope phase-N`, nurture MUST also own the commit and `.gitignore` responsibilities defined in the shared procedure at `$BRAINS_PATH/references/commit-procedure.md`. Follow that procedure verbatim.

### 5. Fix Issues

Work through the issue list in priority order:

- **P0 (Bugs):** Fix immediately. Run tests after each fix.
- **P1 (Missing features/tests/docs):** Implement features per the design spec, write E2E tests for missing coverage, AND update `README.md` / `CHANGELOG.md` for any user-visible behavior change in scope. If no `CHANGELOG.md` exists, file a follow-up beads task rather than creating one unilaterally (the project may use a different release-notes convention).
- **P2 (Code quality):** Fix only what materially affects readability or maintainability.

For each fix:
1. Make the change
2. Run relevant tests
3. Verify the fix doesn't break other functionality
4. Commit atomically with a descriptive message

### 6. Verify

After all fixes:

- Run the full test suite
- Verify E2E tests pass
- Check that all P0 and P1 issues are resolved
- Confirm no regressions were introduced

If tests fail, diagnose and fix before proceeding.

## Output

If significant changes were made, update the implementation plan or create a nurture report:

```markdown
# Nurture Report: [Topic]

## Review Summary
- Files reviewed: N
- Issues found: N (P0: X, P1: Y, P2: Z)
- Issues fixed: N
- Council providers: [if applicable]

## Issues Fixed
1. [description] — [commit hash]
2. ...

## Tests Added
1. [test description] — [file]
2. ...

## Remaining Items
[Any P2 issues deferred]
```

Write to `docs/plans/YYYY-MM-DD-<topic>-nurture.md` if a report is warranted. Commit to git.

When invoked with `--scope phase-N`, additionally:

- Report file: `docs/plans/<slug>-phase-<N>-nurture.md`
- Follow-up tasks filed to beads with label `brains:phase-<N+1>` (if next phase exists) or `brains:cleanup`.

Close the `Nurture: phase <N>` umbrella task on completion.

## Phase Transition

After nurture completes:

> "Nurture phase complete. [N] issues found, [M] fixed. Tests passing.
>
> Next steps:
> - `/brains:secure` — security review and hardening
> - `/brains:brains` — continue the full BRAINS pipeline"

## Additional Resources

- **`$BRAINS_PATH/references/multi-llm-protocol.md`** — shared multi-LLM invocation protocol