# Nimrod QRSPI Adaptation

## Purpose

This workflow adapts QRSPI — Question, Research, Structure, Plan, Implement — to this repository's lightweight ticket/spec operating model.

Use it when a request is complex, risky, multi-file, infrastructure-related, security-sensitive, or likely to exceed one context window.

## Core Context-Management Rule

Each phase writes a markdown artifact. Later phases read only the artifacts listed for that phase, plus explicitly approved files needed for that phase.

Use sub-agent or role isolation as the standard way to reduce context rot. When the harness supports real subagents, delegate narrow tasks to them. When it does not, emulate subagents with separate role-labeled passes that read only their allowed inputs and write a bounded artifact.

This emulates strong context isolation even when the tool cannot technically prevent the assistant from reading extra context.

The assistant should state which artifacts it is reading at the start of each phase.

## Standard Sub-Agent / Role Passes

Use these roles for QRSPI-style work:

| Role | Purpose | Reads | Writes |
|---|---|---|---|
| Locator | Find where relevant files/docs/systems live | ticket/context only | location notes inside `01-questions.md` or `02-research.md` |
| Researcher | Gather facts without proposing solutions | `01-questions.md` | `02-research.md` |
| Analyzer | Trace how an existing flow works | narrow research prompt + relevant files | section of `02-research.md` |
| Pattern Finder | Find similar examples/patterns | narrow research prompt + relevant files | section of `02-research.md` |
| Designer | Turn facts into options and decisions with user input | ticket/context + research | `03-design.md` |
| Structurer | Break approved design into vertical slices | research + design | `04-structure.md` |
| Planner | Produce tactical checklist | research + design + structure | `05-plan.md` |
| Implementer | Execute one checked phase at a time | `05-plan.md` + current files only | code/docs + checked plan items |
| Reviewer | Verify diff against design/plan | design + plan + diff/test output | `06-review.md` |

The important rule is that each role has a narrow job and should not do the next role's work early. For example, Researcher records facts and patterns but does not choose the design; Implementer follows the plan and does not expand scope.

## Pi Implementation

Pi does not ship with built-in Claude-style subagents by default, so Nimrod provides a project-local robust subagent MVP:

```text
.pi/extensions/nimrod-subagents/
.pi/agents/nimrod-*.md
```

The extension registers the `nimrod_subagent` tool, adapted from Pi's example subagent extension. It spawns isolated child `pi` processes in JSON mode and supports single, parallel, and chained subagent execution.

Use `nimrod_subagent` as the standard mechanism for context-heavy Nimrod/QRSPI work when available. The parent assistant should delegate narrow research, analysis, planning, implementation, or review tasks to the relevant `.pi/agents/nimrod-*.md` role agent and have that subagent write the specified QRSPI artifact directly when appropriate.

If the extension is unavailable or not reloaded yet, fall back to procedural role passes using this document and the artifact templates.

Safety model:
- Use narrow task prompts and explicit artifact paths.
- Use git status/diff review as the primary rollback control.
- Prefer one phase at a time for write-capable agents.
- Do not commit when unrelated dirty work exists unless explicitly instructed.

## Artifact Layout

Tickets remain in `tickets/active/` as normal. QRSPI-style artifacts live beside the ticket in an artifact directory:

```text
tickets/active/YYYY-MM-DD-short-title.md
tickets/artifacts/YYYY-MM-DD-short-title/
├── 00-context.md      # optional durable background/constraints
├── 01-questions.md    # neutral research questions
├── 02-research.md     # factual findings only
├── 03-design.md       # user-aligned direction and decisions
├── 04-structure.md    # vertical slices and verification checkpoints
├── 05-plan.md         # tactical implementation plan with checkboxes
└── 06-review.md       # verification, diff notes, follow-ups
```

For project-specific work, a project may also keep a stable spec at `projects/<name>/spec.md`, but the per-ticket artifact directory is the source of truth for resumable phase work.

## Phase Flow

### 0. Ticket / Context

**Reads:** user request, existing ticket if any, relevant project docs if approved.

**Writes:**
- `tickets/active/<id>.md`
- optional `tickets/artifacts/<id>/00-context.md`

Capture the goal, why it matters, scope, acceptance criteria, known constraints, and open questions.

### 1. Questions

**Reads:** ticket and optional `00-context.md`.

**Writes:** `01-questions.md`.

Create 3–7 neutral, fact-seeking questions. Questions should discover what exists, what constraints apply, and what decisions are needed. Avoid embedding the intended solution.

### 2. Research

**Reads:** `01-questions.md` only, plus files/systems required to answer those questions.

**Does not read:** design, plan, or solution notes.

**Writes:** `02-research.md`.

Document facts with file paths, command outputs, source links, or system references. Do not propose solutions in this phase.

### 3. Design

**Reads:** ticket, `00-context.md` if present, `01-questions.md`, and `02-research.md`.

**Writes:** `03-design.md`.

Before writing the design, ask the user 3–5 judgment questions when there are meaningful trade-offs. Then document current state, desired state, decisions, non-goals, risks, and acceptance criteria.

### 4. Structure

**Reads:** `02-research.md` and `03-design.md`.

**Writes:** `04-structure.md`.

Break the work into vertical slices. Each slice should be independently testable and preferably independently revertable.

### 5. Plan

**Reads:** `02-research.md`, `03-design.md`, and `04-structure.md`.

**Writes:** `05-plan.md`.

Create the agent's tactical checklist: exact files, commands, verification steps, rollback notes, and implementation checkboxes. No open questions should remain.

### 6. Implement

**Reads:** `05-plan.md` first, then only files needed for the current checked phase.

**Writes/updates:** code/config/docs, `05-plan.md` checkboxes, `06-review.md`, and server change log when applicable.

Implement one phase at a time. Run verification before moving on. Commit logical phases when the repository state allows it.

### 7. Review / Close

**Reads:** `03-design.md`, `05-plan.md`, git diff, verification outputs.

**Writes:** `06-review.md`, ticket status update, relevant docs/runbooks/change logs.

Summarize what changed, how it was verified, remaining risks, rollback path, and follow-up tickets.

## Greenfield Adaptation

For new software, Research is not only codebase research. It may include:

- user workflow and acceptance criteria
- comparable tools or examples
- framework/library options
- deployment/runtime constraints
- data model constraints
- security and privacy requirements
- operational/runbook requirements

Keep the same separation: Research records facts and options; Design makes choices.

## Small Task Shortcut

Do not use the full workflow for everything.

| Task size | Suggested flow |
|---|---|
| Tiny fix | Brief plan → implement → verify |
| Small feature | Ticket → plan → implement |
| Medium feature | Ticket → questions/research → design/plan → implement |
| Large or risky work | Full Nimrod QRSPI |

## Context Isolation Checklist

At the beginning of each phase, the assistant should say:

```text
Phase: <name>
Allowed reads: <artifact/files>
Will write: <artifact>
Stop conditions: <when to ask user before proceeding>
```

If the assistant needs to read outside the allowed inputs, it should state why and keep the finding in the output artifact.

## Stop Conditions

Stop and ask the user when:

- research questions are too vague to answer usefully
- design requires a human preference or trade-off decision
- plan expansion reveals missing information
- implementation finds reality differs materially from the plan
- an action is destructive, security-sensitive, or data-affecting
- verification fails in a way that changes scope or design