notque/pair-programming

Pair Programming Skill

Collaborative coding through the Announce-Show-Wait-Apply-Verify micro-step protocol. The user controls pace, sees every planned change as a diff, and confirms before any file is modified. Works with any domain agent as executor.

This skill runs in the main session (not context: fork) because every step requires an interactive user gate — forking would execute autonomously and break the confirmation protocol.

Instructions

Session Setup

1. User describes what they want to build. Read relevant code to understand the starting point.
2. Create a high-level plan. Break the task into numbered steps, each representing one logical change. Show the numbered step list to the user before starting any micro-steps.
3. Confirm the plan. Wait for user acknowledgment before starting Step 1. The user may reorder, remove, or add steps.

Maintain step count, current speed setting, and remaining plan throughout the session so you can display "Step N of ~M" with each announcement. The user needs this orientation to stay engaged with the collaborative flow.

Micro-Step Protocol (Per Change)

For each step in the plan, execute this 5-step protocol:

1. Announce — Describe the next change in 1-2 sentences: what will change and why. Keep announcements brief (1-2 sentences) before showing code immediately because the user came to code together, not to read an essay. Long explanations break flow and reduce collaborative momentum.

2. Show — Display the planned code as a diff or code block. The current step size limit (default 15 lines, max 50 lines) exists because users cannot make informed decisions about changes they have not seen. Every change gets shown—even trivial ones, which are fast to approve—so you and the user stay synchronized. Never exceed the limit: split large changes into sub-steps instead.

3. Wait — Stop and let the user respond with a control command. Do not proceed until you receive an explicit command—assuming the user will say "ok" and applying preemptively turns this into autonomous mode with a running commentary, violating the micro-step protocol.

| Command | Action | |---------|--------| | ok / yes / y | Apply current step, proceed to next | | no / n | Skip this step, propose alternative approach | | faster | Double step size (max 50 lines) | | slower | Halve step size (min 5 lines) | | skip | Skip current step entirely, move to next | | plan | Show remaining steps overview | | done | End pair session, run final verification |

4. Apply — Execute the change only after receiving ok/yes/y. Never apply changes without explicit confirmation—doing so turns collaborative pair programming into autonomous mode with a running commentary.

5. Verify — Run relevant checks (lint, type check, test) and report results in one sentence. Catching errors immediately keeps the codebase green and prevents error accumulation across steps, ensuring every change is validated before moving forward.

If a step exceeds the current size limit, split it into sub-steps (Step 3a, 3b, 3c). Announce the split: "This change is ~40 lines. I will split it into 3 sub-steps." This splitting exists because the user must be able to approve or reject individual logical changes—bundling multiple logical changes into one step to avoid splitting defeats the purpose of the micro-step protocol.

Speed Adjustment

Sessions start at 15 lines per step, balancing progress with reviewability. Apply speed changes immediately when the user requests them and acknowledge the new setting because ignoring pace signals breaks trust and the user's sense of control. The user must feel they are the one steering the session.

| Setting | Lines Per Step | Trigger | |---------|---------------|---------| | Slowest | 5 | Multiple slower commands | | Slow | 7 | slower from default | | Default | 15 | Session start | | Fast | 30 | faster from default | | Fastest | 50 | Multiple faster commands (hard cap) |

When the user says faster or slower, acknowledge the change: "Speed adjusted to ~N lines per step."

Session End

When the user says done or all steps are complete: run final verification (lint, type check, full test suite), show a summary (steps completed, steps skipped, files modified), and report verification results. This end-of-session gate ensures the codebase is left in a valid state.

Examples

Standard Session — User says: "Pair program a function that parses CSV lines in Go"

1. Read existing code, create 5-step plan (struct, parser func, error handling, tests, integration)
2. Show plan, wait for confirmation
3. Step 1: Announce "Define a CSVRecord struct" — show 8-line struct — wait — user says ok — apply — verify
4. Step 2: Announce "Add ParseLine function" — show 12-line function — wait — user says ok — apply — verify
5. Continue through remaining steps

Speed Adjustment — User says faster after Step 2

1. Acknowledge: "Speed adjusted to ~30 lines per step."
2. Next step shows up to 30 lines instead of 15
3. If user says slower later, drop to ~15

Session End — User says done after Step 4 of 6

1. Run go vet, go test ./...
2. Report: "4 of 6 steps completed, 0 skipped. Modified: parser.go, parser_test.go. Tests: all passing."

Error Handling

User Says "Just Do It" / Wants Autonomous Mode

Cause: User wants speed, not collaboration. Solution: Acknowledge the preference and offer to switch. Say: "Would you like to switch to autonomous mode? I can implement the remaining steps without confirmation." If they accept, drop the micro-step protocol and implement normally.

Verification Fails After a Step

Cause: Applied change introduces a lint error, type error, or test failure. Solution: Announce the fix as the next micro-step. Show the fix diff, wait for confirmation, apply, re-verify. Do not silently fix verification failures regardless of cause—silent fixes violate the protocol.

Step Too Large to Fit Size Limit

Cause: A logical change requires more lines than the current limit. Solution: Split into sub-steps (Step 3a, 3b, 3c). Each sub-step stays within the limit. Announce the split: "This change is ~40 lines. I will split it into 3 sub-steps."

References

• Micro-step protocol control commands — user command table
• Speed adjustment table — lines-per-step settings