# Requirements: ad-hoc-pair-programming — Pair Programming Prompt & Workflow

## Status
✅ Approved — immutable as of 2026-04-07

## Summary

`pair-programming.prompt.md` is a new workflow prompt that implements a ticket one step at a time in close collaboration with the human. The coding agent reads the approved implementation plan, presents its work for each step, and waits for explicit human approval before committing and advancing. Inline corrections trigger a re-implementation loop on the current step. This tighter feedback loop keeps each reviewable chunk small, makes mid-course corrections cheap, and produces a clean commit history where every commit is independently reviewable.

## Acceptance Criteria

- [ ] AC-1: A `pair-programming.prompt.md` file exists in `.github/prompts/`.
- [ ] AC-2: The prompt reads `requirements.md` and `implementation-plan.md` at session start and derives the ordered step list from them; if `implementation-plan.md` is absent, falls back to the `## Implementation Plan` section of `requirements.md`.
- [ ] AC-3: The prompt implements exactly one step per round and pauses with a concise summary before any commit.
- [ ] AC-4: Any non-approval reply (inline correction, question, or feedback) is treated as a correction — the agent re-implements the step and presents a new diff before waiting for approval again.
- [ ] AC-5: An explicit approval keyword (`ok`, `works`, `approved`, `looks good`, `yes`, `proceed`, `next`) commits the step with the message `feat/fix: step X -- <description> <TICKET_ID>` and advances to the next step.
- [ ] AC-6: For medium/large steps (≥3 files changed, or any new export/interface), `typecheck` and `lint` pass before the step is presented to the human.
- [ ] AC-7: Cache and findings are updated after every step is committed.
- [ ] AC-8: Ad-hoc mode is supported — if no approved `requirements.md` exists, the user provides a description and the agent creates a minimal step list; TICKET_ID defaults to `NOISSUE`.

## Key Decisions

| # | Decision | Rationale |
|---|---|---|
| D-1 | Prompt file only (`pair-programming.prompt.md`) — no new agent | The coding agent already handles implementation; this prompt just adds the human-in-the-loop gate |
| D-2 | Step list derived from `implementation-plan.md` (fallback: `requirements.md`) | Reuses the already-approved plan; avoids re-deriving intent from scratch each session |
| D-3 | Ad-hoc mode supported with `NOISSUE` fallback | Mirrors the flexibility of `problem-refinement.prompt.md`; allows exploratory work without prior refinement |
| D-4 | Corrections re-trigger the current step, not a new step | Keeps commit history clean — each commit = one approved step, never a partial or corrected state |
| D-5 | Complexity gate: small (≤2 files, no new exports) = human-only; otherwise `typecheck` + `lint` required | Human cannot realistically test medium/large changes without the project compiling; small changes are safe to eyeball |
| D-6 | Cache updated after every committed step | If the context window resets mid-ticket, the human can resume from the last committed step without information loss |

## Data Model

Not applicable — the deliverable is a markdown prompt file, not a data-driven feature.

## UX / UI Specification

Not applicable — no UI changes.

## API Contracts

Not applicable — no new API or SDK calls.

## DQL Queries

Not applicable.

## Implementation Plan

### Consumer Impact Analysis

No TypeScript interfaces are changed by this ticket. The new prompt file is standalone.

| Artefact | Change |
|---|---|
| `.github/prompts/pair-programming.prompt.md` | New file — created |
| `.github/base/prompts-definition.md` | Add one-line entry for the new prompt to the catalogue |
| `AGENTS.md` | Add one row to the Prompt Catalogue table (Section 6) |

### Step 1 — Create `pair-programming.prompt.md`
- **File**: `.github/prompts/pair-programming.prompt.md`
- **Changes**: Write the full prompt following the structure of `implementation.prompt.md` but with a step-locked loop, correction handling, complexity-gated `typecheck`/`lint`, per-step commits, and cache updates.
- **Verification**: Read through the prompt and verify all ACs are covered; check that the commit message format, correction loop, approval keywords, and ad-hoc mode are explicitly described.

### Step 2 — Register the prompt in the catalogue and AGENTS.md
- **Files**: `.github/base/prompts-definition.md`, `AGENTS.md`
- **Changes**: Add the new prompt row to both catalogue tables.
- **Verification**: Both tables reference `pair-programming.prompt.md` with correct trigger description.

## Unit Test Plan

Not applicable — deliverable is a markdown prompt file; no TypeScript code is produced.

## Edge Cases & Error Handling

- **`typecheck` or `lint` fails on a medium/large step**: Follow `error-recovery.skill.md` — fix and re-run up to 3 times; if still failing, escalate to the human before presenting the step (never present broken code).
- **Human sends ambiguous message** (e.g. "hmm", "not sure"): Treat as a correction prompt — ask one targeted clarifying question, re-implement if clarified, otherwise hold on the current step.
- **Context window reset mid-ticket**: Resume by reading `cache.md` — the last committed step number is recorded there; skip to the next uncommitted step.
- **`implementation-plan.md` absent and `requirements.md` has no `## Implementation Plan` section**: Ask the human to provide the step list before proceeding; do not invent steps.
- **Step description is ambiguous** (no clear file path or change description): Ask one clarifying question before coding, not after.
- **Ad-hoc mode with no existing folder**: Create `.github/tickets/NOISSUE/` (or `ad-hoc-<slug>/` if a slug is provided), write a minimal step list from the user's description, then start step 1.

## Out of Scope

- **Agent Smith FULL per step**: Too heavy for a single-step review loop; reserved for the `implementation.prompt.md` full-cycle workflow.
- **Parallel unit test + component test phases per step**: Testing steps are defined in the implementation plan as explicit steps; no automatic test phase is injected between code steps.
- **Multi-CL mode within the pair-programming prompt**: Each step is already an independently reviewable unit; CL splitting adds no value here.
- **PR / changeset creation**: Out of scope for this prompt; handled by the developer after all steps are complete.

