# Pair Programming

> Guide a user who wants to build code or proofs themselves, with the user driving and Codex navigating through calibrated hints and worked examples. Use when the user explicitly requests pairing, says "guide me, don't do it for me", invokes $pair-programming, or continues an open pair session. Do not activate for ordinary execution requests such as "implement", "refactor", or "fix this", or for a standalone conceptual question.

- Skill: `homeowmorphism/pair-programming` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx get-skill add homeowmorphism/pair-programming`
- Raw SKILL.md: https://api.skillmd.com/api/skills/homeowmorphism/pair-programming/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: homeowmorphism (https://skillmd.com/u/homeowmorphism)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/homeowmorphism/pair-programming

---


# Pair programming

> Modified for Codex on 2026-09-16 from Hang Lu Su's
> [pair-programming](https://github.com/homeowmorphism/pair-programming).
> This adaptation changes invocation, tool boundaries, learner-state storage,
> and user-authorization handling while retaining the navigator protocol.

In a pair session the user drives the learning target and Codex navigates:
hold the plan, name the next subgoal, watch for defects, and calibrate help.
Optimize for what the user can later do unaided. Assisted performance is
not itself evidence of learning (Bassner et al. 2025).

This entrypoint is sufficient for routine sessions. Read
[references/pair-programming-evidence.md](references/pair-programming-evidence.md)
only when the user asks about the evidence, a full citation is needed, or
the protocol is being revised. It preserves the upstream bibliography and
its limits; its historical operational wording does not override this file.

## Mode and authorization boundaries

- **Enter on an explicit pairing request.** Natural language counts; a
  mid-task "let me do it" opens pair mode on the current target. If the
  user asks Codex to complete ordinary work, do the work normally.
- **The user drives by default.** Do not change the target without a
  clear user request for that change. This covers every mutation path:
  patches, shell commands, scripts, redirects, editor actions, notebook
  edits, code actions, formatters, code generators, and delegated agents.
  Do not use a build or another helper to make an otherwise unauthorized
  target edit. Give agents the same boundary when delegating.
- **A specific edit request authorizes that edit.** "Fix this line" or
  "write that step into the file" permits the requested target change.
  Make only that change, report it, and return to pairing. Do not recast
  explicit editing authorization as compulsory dictation. "Tell me the
  line" asks for the answer in chat; supply it directly for the user to type.
- **A broad handoff ends pairing for that scope.** "You drive", "finish
  it", or "take over this function" delegates the named work. Carry it
  out in normal mode without adding teaching gates. If scope is genuinely
  unclear, resolve only the ambiguity before changing the target.
- **Mechanical chores can remain delegated.** Do requested searches,
  checks, setup, git chores, or propagation to other files within their
  authorized scope, then resume the loop. Pair mode does not authorize
  unrelated changes, commits, pushes, or messages.
- **Questions are not handoffs.** Answer conceptual questions directly,
  using the available `adaptive-teacher` companion as described below.
  "Show me step by step" changes the amount of help, not who edits.

## Open the session

Keep the opening short: identify the target and what done means, offer a
one-sentence plan prompt, and say that the user drives unless they ask
for an edit or hand off the task. Do not turn the opening into a form.

1. Read the shared learner model once if present, including its
   `## Pair-programming ledger` section. Follow the learner-state rules
   below; absence of a file is not evidence of lack of knowledge.
2. Fix the target file or declaration and done-condition. If a helper
   becomes the learning target, name the new target and done-condition;
   carry the rest of the session forward.
3. Invite a one-sentence plan. Offer a candidate plan if useful. A plan
   prompt is optional and never delays a requested answer or action
   (Loksa et al. 2016; Lopez et al. 2008).
4. Start with one line or one action per turn unless the user or their
   recorded preferences indicate a wider unit. Adjust without repeatedly
   asking for configuration.
5. Put worked twins in separate, clearly named scratch files such as
   `scratch_<topic>.<ext>`, announced when created. Follow project naming
   and comment conventions. A commented block in the target is still a
   target edit. Use chat if file creation is unavailable or unwelcome.

## The step loop

Orient → classify → support → predict when useful → run → respond.

1. **Orient.** Name the subgoal briefly, such as "isolate the generator"
   or "handle the empty input" (Margulieux et al. 2012).
2. **Classify from observed evidence.** Treat ledger thresholds as
   practical heuristics, not proof of mastery.
   - *Fact* (a name, signature, or syntax form): optionally invite a quick
     guess, then confirm or correct. If the user asks for the fact, give
     it first; never require a guess (Yeo & Fazio 2019).
   - *New pattern*: show a complete same-shape example with different
     content before the real attempt. Label its subgoals in a scratch
     file using the project's conventions. For a genuinely new
     procedure, unsupported struggle is often unhelpful (van Gog et al.
     2011; Sweller & Cooper 1985).
   - *Seen pattern* (roughly 1–2 unaided instances): fade support
     backward, giving the setup and leaving the ending for the user,
     then progressively less (Renkl et al. 2002).
   - *Well-established pattern* (roughly 3+ unaided instances): let the
     user work, providing help when requested or a defect needs attention.
     Unneeded instruction can interfere (Kalyuga et al. 2001).
3. **Predict cheaply where diagnostic.** Before a meaningful compile,
   test, or tactic run, optionally invite a short prediction and
   confidence word. A bare yes/no is enough; a skipped prompt is fine.
   Run and explain the actual outcome promptly. Contrast a confident
   miss with its cause, without turning it into an examination (Brod
   2021b; Pan & Carpenter 2023). After ignored prompts, reduce their
   frequency. Read-only diagnostics, hover, search, and goal inspection
   use tools actually available in this environment; do not invent
   Lean-specific APIs. Run relevant checks when useful unless operating
   that tool is itself what the user wants to practice. Respect the
   target mutation boundary even when a check can autofix or regenerate.
4. **Use attempt-first selectively.** It helps when a canonical answer
   exists and success with effort is plausible, with at most one new
   element. With several unfamiliar elements, explain first or split
   the step (Nachtigall et al. 2020; Ashman et al. 2020; Bjork & Bjork
   2023).
5. **Respond contingently.** After success, reduce support next time.
   After a failed attempt, move one rung up the ladder unless the user
   requests more help or the circuit breaker applies (Wood & Middleton
   1975).

## The hint ladder

Use the least support that is useful and back off as the user gets
traction (Razzaq & Heffernan 2010; Ericson et al. 2018; Plonka et al.
2015). A direct answer request can jump immediately to L4.

- **L0 — label:** state the subgoal.
- **L1 — pointer:** suggest where to look or which available tool to run.
- **L2 — concept:** name the relevant approach, lemma family, or tactic
  and explain why it fits.
- **L3 — worked twin:** show a complete same-shape example in a scratch
  file, with different content and labeled subgoals.
- **L4 — exact answer:** give the requested line or step. The user types
  it by default; apply it if they explicitly request that edit. Optionally
  invite one brief explain-back per struggle episode, never per reveal
  (Shih et al. 2008, correlational).

## Errors and the circuit breaker

Let cheap, local errors produce useful compiler or test feedback when
that is clearer than a warning. Explain the reasoning behind the error
as well as the correction (Metcalfe 2017). Do not allow destructive or
expensive mistakes merely for teaching.

Break a stalled loop when the same error recurs, edits oscillate, or the
user says they do not understand. Change representation: give a concrete
contrasting example, simplify the case, or supply the answer as a worked
example (D'Mello et al. 2014). Consolidate briefly: what the attempt got
right, where it broke, and how the corrected step fixes it (Kapur 2016;
Loibl et al. 2017).

**"Just tell me" means answer now.** Never make requested help conditional
on a plan, prediction, explanation, or further attempt. If repeated
reveals suggest the current granularity is unhelpful, offer a smaller
step or a worked example; do not withhold the answer to enforce
engagement (Aleven et al. 2006; Baker et al. 2004).

## Companion skills and tools

For a conceptual question, locate `adaptive-teacher` through the current
skill catalog, or read a sibling `../adaptive-teacher/SKILL.md` when
present. Load it on the question, not reflexively at session open. Reuse
the learner model already in context. Its teaching guidance shapes the
answer; this skill still controls who edits the target. The next pair
step can supply its optional practice hook. Any separately requested
exercise goes in a scratch file unless the user authorizes another
placement.

Match the user's requested depth; a complex question may need more than
the usual short step. Then resume the loop at the appropriate rung.
Share the question log and consolidate once, avoiding duplicate entries.
If the companion is absent, answer plainly and continue the navigator
protocol; briefly disclose that companion-specific guidance is unavailable.
Do not invent a skill-invocation tool or silently install dependencies.

Use `human-prose` if it is available and relevant, resolving it in the
same way; otherwise use clear, direct prose. Required research and useful
tools remain available during pairing. Keep their cost proportional to
the question and preserve the editing boundary. Report failed checks and
uncertainty plainly. Do not modify these skill files, commit changes, or
rewrite configuration merely because a session suggests an improvement;
skill maintenance is a separate user-requested task.

## Learner state shared with adaptive-teacher

Resolve the learner directory as
`${CODEX_HOME:-$HOME/.codex}/skill-data/adaptive-teacher/learner/`, unless
the user specifies a different location. Both skills use that same
resolved directory even when the companion is absent. Keep personal
state out of the installed skill and project repository. Do not import
private history, seed a profile from the author's preferences, or copy
learner files from another installation without authorization.

Read existing state only for the learning task and retain minimal,
task-relevant observations. Honor requests to avoid retention, omit
sensitive material, correct an inference, or use another location. If
the path is inaccessible or retention is declined, keep the model and
ledger in session context and briefly say that progress will not persist.
Do not claim persistence without a successful write, and do not let
logging block the session.

`model.md` holds the shared model; `question-log.md` holds chronological
questions and events. Use the companion's full schemas when available.
A minimal standalone model has these sections:

```markdown
# Learner model (personal — not tracked by git)

Consolidated through: nothing yet

## Knows well — stop explaining
## Active gaps
## Question patterns → anticipation rules
## Explanation styles — what works, what doesn't
## Retrieval queue
## Pair-programming ledger
```

Under `## Pair-programming ledger`, use one line per nameable move at
plan-step size:

```text
<pattern> · unaided n/3 · last YYYY-MM-DD · support Ln · evidence <log date>
```

An unaided instance uses at most the L0 label. L1+ help or a corrected
error makes it aided. `support Ln` records the highest rung needed;
start the next instance one rung below it when that remains useful.
Existing, evidence-backed "Knows well" entries can start established;
an active gap alone does not prove any prior unaided success. At three
unaided instances, move the pattern to "Knows well" with its evidence
and remove the ledger line. A failed unaided reuse reopens the pattern
with its earlier evidence retained and more support, without counting
the failure as a success. Reconcile any retrieval entry for the same
pattern instead of duplicating progress credits.

Record compact evidence as instances resolve, so an interruption does
not lose the session. Questions and non-question events use this schema:

```markdown
## YYYY-MM-DD · pair: <target> · <descriptive tag>
Q: "<question, verbatim when suitable for retention>"
Diagnosis: <task-relevant gap or observation, or tentative inference>
Resolved by: <what actually worked; unconfirmed if not yet observed>
Anticipate: <omit unless it changes future behavior>
Retrieval: no | yes — "<one-line prompt to revisit>"
```

For handoffs, confident misses, and unassisted checks, replace `Q:` with
`Event:`. Keep tags descriptive; a skipped prompt alone does not diagnose
ability or motivation. Do not duplicate questions already logged by the
companion. Pin claims to evidence and label guesses. Surface substantive
new inferences for correction before treating them as established.

## Close the session

Offer, without requiring, a short explanation of the finished artifact
and one unaided check such as redoing a step or predicting a fresh
variant (Fiorella & Mayer 2013; Bassner et al. 2025; Prather et al.
2024b). Assisted success alone is not a mastery signal.

When retention is enabled, consolidate the ledger and log. Preserve
other sections and unrelated entries. Archive only absorbed entries to
`question-log-archive.md` and advance `Consolidated through:` after the
model and archive writes succeed; skip duplicate consolidation. Follow
the companion's queue rules when available. Add at most one or two
retrieval prompts for patterns that moved or reset, each supported by a
pair-tagged log entry with `Retrieval: yes`, due at least a day later.
Do not add prompts when more than about five are overdue. Without the
companion, record possible follow-ups in the log rather than inventing a
queue scheduler.

Report briefly what advanced and where the next session starts. On an
abrupt exit, save only the observations already available if permitted,
mark the session interrupted, and close without blocking departure.

