| name | pair-next |
| description | Determines the most relevant next action for your project by reading adoption files and PM tool state. Suggests which skill to invoke next. Use at the start of a session, when switching tasks, or whenever you need guidance on what to work on. |
| version | 0.5.0 |
| author | Foomakers |
/pair-next — Project Navigator
Analyze project state and recommend the single most relevant next skill to invoke. Covers the full 38-skill catalog across all lifecycle phases.
Arguments (optional)
/pair-next accepts two optional arguments that SCOPE which backlog items it may select. With neither, it behaves exactly as before — the whole backlog is in scope. This scoping is what makes /pair-next the parametrizable atom of automation.
| Argument | Value | Effect |
|---|
--root | an issue id (epic or story) | Restrict selection to that issue's subtree in the PM hierarchy. |
--filter | a single tag/label (e.g. ui, risk:red) | Restrict selection to issues carrying that exact label. |
Both may be combined — the effective scope is the intersection: subtree ∩ matching tags (see Step 0).
--root <issue-id> — subtree scope
Resolve the issue's descendants through the PM-tool parent/child hierarchy (sub-issues / parent links), never through title conventions. Selection is confined to that subtree — nothing outside it is ever proposed.
- Epic root → operate at epic level: plan / refine / develop the epic's children only.
- Story root → operate on that story: refine or develop it (and its tasks); never step outside it.
The root issue is itself a first-class member of the candidate set, alongside its transitive children; a scoped run is a backlog-item query over that set. The item-selection rows (6–11) of Step 3 and Step 4 row 16 (/pair-capability-grill) run against the candidate set instead of the full backlog — so a Draft story root selects /pair-process-refine-story on itself, a Ready story root selects /pair-process-implement (or /pair-process-plan-tasks), and nothing outside the set is ever proposed. The project-wide detectors are never surfaced under a scope: Step 2 (fresh-project detection) and Step 4 rows 12–15 (gate / stack / debt / estimation config) answer whole-project questions — not "which item in this subtree" — so a scoped run does not emit them; if the candidate set yields no actionable item, the run exits cleanly (Step 0 item 5) rather than falling through to them. Step 3 rows 3–5 (/pair-process-plan-initiatives, /pair-process-plan-epics, /pair-process-plan-stories) are structural planning-gap detectors evaluated root-relatively, never fired by a subtree's mere absence of a higher layer: a story root skips rows 3–5 entirely and begins at row 6 (its planning layers already exist), while an epic root keeps row 5 scoped to itself — an epic with no user-story children selects /pair-process-plan-stories (the epic-root "plan its children" action) — and skips rows 3–4 (an epic contains no initiatives or epics). Under a --filter-only scope (no root) there is no subtree, so rows 3–5, like the other project-wide detectors, are not surfaced.
--filter <tag> — generic tag match
Keep only candidate issues that carry the given label. --filter takes a single label string, not a boolean expression — there is no AND/OR/NOT grammar; the whole argument is matched literally against each issue's labels. The tag is interpreted GENERICALLY: /pair-next assigns NO meaning to any tag value. risk:red is matched by exactly the same string-equality predicate as team:ui — there is no classification, tiering, or severity logic anywhere in this skill (D18). A namespaced-looking label such as tag:ui carries no namespace semantics either: the whole string (colon included) is one opaque label, matched entire — so --filter tag:ui selects issues labelled literally tag:ui, exactly as --filter ui selects issues labelled ui. A filter is a plain PM-tool label query, nothing more.
Re-evaluation — selection is never cached
The scope is stateless across steps. Every run — and every step of a multi-step run — re-queries the PM tool and re-evaluates --root and --filter against the current board state. If an issue's tags change between steps (e.g. a review raises risk:yellow → risk:red), the next step's selection reflects the change immediately. /pair-next never reuses a selection computed in a previous step.
Skill Catalog (38 skills)
The catalog is derived from the installed corpus: every skill directory under .skills/ must appear here — 9 process + 28 capability + /pair-next itself = 38. If an installed skill is missing from these tables (or a row names a skill that is not installed), the catalog has drifted: update the tables, the stated counts, and the cascade rows together.
Process Skills (9)
| Skill | Lifecycle Phase | Description |
|---|
/pair-process-specify-prd | Induction | Create or update Product Requirements Document |
/pair-process-bootstrap | Induction | Orchestrate full project setup |
/pair-process-plan-initiatives | Strategic | Create strategic initiatives from PRD |
/pair-process-plan-epics | Strategic | Break initiatives into epics |
/pair-process-plan-stories | Sprint Planning | Break epics into user stories |
/pair-process-refine-story | Sprint Planning | Refine story with AC and technical analysis |
/pair-process-plan-tasks | Sprint Planning | Break story into implementation tasks |
/pair-process-implement | Sprint Execution | Implement story tasks with TDD |
/pair-process-review | Sprint Execution | Review PR through structured phases |
Capability Skills (28)
| Skill | Category | Description |
|---|
/pair-capability-map-subdomains | Domain Modeling | Scoped DDD subdomain placement (+ Volatility) |
/pair-capability-map-contexts | Domain Modeling | Scoped DDD bounded-context placement + relationship assessment |
/pair-capability-classify | Classification | Apply the quality model → risk/cost matrix + tags (composed by refine-story, review) |
/pair-capability-grill | Alignment | Interview engine: explore a topic or sync on a story, one question at a time |
/pair-capability-record-decision | Decision | Record ADR or ADL with adoption update |
/pair-capability-checkpoint | Session State | Write/resume story progress checkpoint (work survives context resets) |
/pair-capability-publish-pr | Delivery | Publish a story branch as a PR: gate, PR from template, tags, board state |
/pair-capability-write-issue | PM Tool | Create/update issues in adopted PM tool |
/pair-capability-setup-pm | PM Tool | Configure project management tool |
/pair-capability-verify-quality | Quality | Check quality gates against codebase |
/pair-capability-verify-done | Quality | Check Definition of Done criteria |
/pair-capability-verify-adoption | Quality | Check code against adoption files per scope |
/pair-capability-assess-stack | Assessment | Assess tech stack (lifecycle-spanning) |
/pair-capability-assess-architecture | Assessment | Assess architecture pattern |
/pair-capability-assess-testing | Assessment | Assess testing strategy |
/pair-capability-assess-ai | Assessment | Assess AI development tools |
/pair-capability-assess-methodology | Assessment | Assess development methodology |
/pair-capability-assess-pm | Assessment | Assess project management tool |
/pair-capability-assess-infrastructure | Assessment | Assess infrastructure strategy |
/pair-capability-assess-observability | Assessment | Assess observability strategy |
/pair-capability-assess-security | Assessment | Assess security posture (review verdict + one-shot audit) |
/pair-capability-analyze-debt | Analysis | Analyze technical debt with prioritization |
/pair-capability-analyze-code-quality | Analysis | Analyze code quality with metrics |
/pair-capability-estimate | Planning | Estimate story using adopted methodology |
/pair-capability-setup-gates | Configuration | Configure CI/CD quality gates |
/pair-capability-manage-flags | Configuration | Manage feature flag lifecycle |
/pair-capability-design-manual-tests | Testing | Generate manual test suite from project analysis |
/pair-capability-execute-manual-tests | Testing | Execute manual test suite + generate report |
Algorithm
Execute these checks in order. Stop at the first match.
Step 0: Resolve Selection Scope (arguments)
Run this before every other step, on every invocation — the result is never carried over from a previous run or step.
- No arguments → the candidate set is the full backlog; skip to Step 1.
--root <id> → resolve the issue via the PM tool.
- Root not found (id does not resolve to an issue): HALT with a clear message (
root <id> not found) and propose no action.
- Root resolves to a Done issue: report that the root is already Done and exit; propose no work.
- Otherwise: the candidate set is the root issue itself plus its transitive children through the PM-tool hierarchy (parent/child links). The root is a first-class member — a childless story or epic root yields a one-issue set, not an empty one — and is itself subject to the item-selection rows (a Draft story root →
/pair-process-refine-story; a Ready story root → /pair-process-implement or /pair-process-plan-tasks). Later steps read this set instead of the full backlog.
--filter <tag> → narrow the candidate set to issues carrying the tag, using a plain string-equality label query (tag-agnostic — no tag value gets special treatment). When --root is absent the candidate set defaults to the full backlog, which --filter then narrows; when --root is present it narrows that subtree.- Both → apply the intersection:
subtree ∩ matching tags.
- Empty candidate set — zero issues (e.g.
--filter matches no issue): report no matching issues and exit cleanly — an empty result is normal, not an error. A childless --root (root with no children) is one issue, not empty: it flows into the cascade (see item 2). A non-empty set whose issues happen to be all non-actionable (e.g. all Done) is likewise not empty here — it falls through to the Step 5 fallback; actionability is decided in Steps 3–4, not by this emptiness check. Item 5's clean exit governs backlog-item selection only: a scoped run that finds no actionable item exits here and does not surface the project-wide config rows 12–15.
The resolved candidate set feeds the scoped Step 3 item-selection (rows 6–11) and Step 4 row 16 (/pair-capability-grill). Step 2 and rows 12–15 (project-wide) are not surfaced under a scope; rows 3–5 are evaluated root-relatively (epic root → row 5 only; story root → skipped) — see Step 3. A scope presupposes an established project (adoption files populated, a real backlog): on a fresh template project --root/--filter are never passed — Step 2 fresh-project detection governs and steers to /pair-process-bootstrap, so the Step 3 "all adoption files populated" premise always holds under a scope. Because Step 0 re-runs each time, a tag mutation between steps changes the selection on the next step automatically.
Step 1: Read Adoption Files
Read the following files and classify each as populated or template:
Template detection rule: A file is a template if it contains square-bracket placeholders (e.g., [Product/feature name]) or if its substantive sections contain no project-specific content.
Step 2: Cascade — Fresh Project Detection
| # | Condition | Suggestion | Rationale |
|---|
| 1 | PRD.md is template | /pair-process-specify-prd | Product vision must come first |
| 2 | PRD.md populated AND 3+ tech adoption files are templates | /pair-process-bootstrap | Project needs foundational setup |
If any of the above matched, output the suggestion and stop.
DDD domain mapping (/pair-capability-map-subdomains, /pair-capability-map-contexts) is a scoped capability, not a mandatory fresh-project step — it is invoked by /pair-process-plan-initiatives, /pair-process-plan-epics, /pair-process-refine-story, /pair-process-plan-tasks, or /pair-process-bootstrap when they touch a capability/context, not suggested directly here. Projects without DDD artifacts fall back to "system areas" gracefully — no HALT.
Step 3: Cascade — Established Project Detection
All adoption files are populated. Query the PM tool to determine backlog state — restricted to the candidate set resolved in Step 0 when --root/--filter are set (re-evaluated every run, never cached). This restriction is scoped to the item-selection rows 6–11 (and Step 4 row 16): it includes row 6's open-PR detection — only PRs whose linked issue is inside the candidate set count — so a PR for an issue outside the subtree/filter is never surfaced as /pair-process-review, preserving the guarantee that nothing outside the scope is ever selected. Rows 3–5 (/pair-process-plan-initiatives, /pair-process-plan-epics, /pair-process-plan-stories) are structural planning-gap detectors, not item selectors, and under --root are evaluated root-relatively — never fired by a subtree's mere structural absence of a higher layer:
- Story root → rows 3–5 are skipped; the cascade begins at row 6 (the story's initiative/epic/story layers already exist, and its candidate set holds no initiatives or epics to plan).
- Epic root → rows 3–4 are skipped (an epic contains no initiatives or epics); row 5 is kept, scoped to the root epic — if it has no user-story children, select
/pair-process-plan-stories. This is the epic-root "plan its children" action AC1 requires.
--filter-only (no root) → there is no subtree; rows 3–5, being project-wide structural detectors, are not surfaced (a scoped run is a backlog-item query).
Rows 12–15 are likewise project-wide and not surfaced under a scope; when the candidate set yields no actionable item, Step 0 item 5's clean exit governs (see Step 0).
PM tool discovery: Read .pair/adoption/tech/way-of-working.md to identify the PM tool (GitHub Projects, Jira, Linear, etc.) and access method.
State resolution: The conditions below refer to canonical macrostates (Draft, Ready, In Progress, Review, Done), never board-specific labels. Resolve each item's board state to a macrostate via the ## State Mapping section in way-of-working.md — omitted ⇒ canonical names are assumed. See canonical-states.md for the full resolution rule. When a board can't distinguish Draft from Ready (no dedicated Ready column), apply the Readiness Fallback: evaluate the Definition of Ready criteria against the item instead of guessing from the board-state name.
| # | Condition | Suggestion | Rationale |
|---|
| 3 | No initiatives or epics exist in PM tool | /pair-process-plan-initiatives | Strategic planning needed |
| 4 | Initiatives exist but no epics | /pair-process-plan-epics | Epic decomposition needed |
| 5 | Epics exist but no user stories (under a --root <epic> scope this is evaluated root-relatively — the root epic's own story children, not the whole board; see the Step 3 header) | /pair-process-plan-stories | Story breakdown needed |
| 6 | Open pull requests, or items resolve to macrostate Review | /pair-process-review | Code review pending — closest to delivery |
| 7 | A story resolves to macrostate In Progress AND its checkpoint file exists (.pair/working/checkpoints/<story-id>.md) | /pair-capability-checkpoint | Resume interrupted work ($mode: resume) before re-analysis |
| 8 | A story resolves to macrostate In Progress but has NO checkpoint file | /pair-process-implement | Continue the in-progress work — /pair-process-implement re-derives state from scratch when no checkpoint exists |
| 9 | Stories resolve to macrostate Ready AND a task breakdown exists | /pair-process-implement | Work is ready to start |
| 10 | Stories resolve to macrostate Ready but have NO task breakdown | /pair-process-plan-tasks | Tasks must be created before implementation |
| 11 | Stories resolve to macrostate Draft (missing acceptance criteria, or failing Definition of Ready via the Readiness Fallback) | /pair-process-refine-story | Stories need refinement before work |
Tie-break: on a real backlog several of rows 6–11 can hold at once (e.g. Draft stories AND an open PR). Row order resolves this — rows are sorted by delivery proximity (/pair-process-review > /pair-capability-checkpoint > /pair-process-implement > /pair-process-plan-tasks > /pair-process-refine-story): evaluate top-to-bottom, stop at the first match. For a single item the distinguishing predicates (macrostate, checkpoint file present/absent, task breakdown present/absent) make rows 7–11 mutually exclusive; across items, row order decides. Every In Progress story matches row 7 or row 8 — the fallback (Step 5) is never reached for active work.
Step 4: Capability Skill Suggestions
If no process skill matched in Steps 2-3, check for capability skill opportunities (same rule: evaluate in order, stop at the first match):
| # | Condition | Suggestion | Rationale |
|---|
| 12 | Quality gate not configured (no Quality Gates section in way-of-working) | /pair-capability-setup-gates | Quality gates should be established |
| 13 | Tech stack has unlisted dependencies detected | /pair-capability-assess-stack | Stack registry needs updating |
| 14 | Technical debt flags present (TODO/FIXME/HACK comments detected) | /pair-capability-analyze-debt | Debt should be cataloged and prioritized |
| 15 | No estimation methodology adopted in way-of-working | /pair-capability-estimate | Estimation process should be established |
| 16 | A backlog item carries open questions or unclear scope (question markers, conflicting comments) that block planning — restricted to the Step-0 candidate set when --root/--filter are set (an out-of-scope item is never surfaced, same as row 6) | /pair-capability-grill | Structured one-question-at-a-time alignment before planning |
Step 5: Fallback
If no condition matched in Steps 2-4:
All adoption files are populated and no actionable backlog items detected.
Consider: starting a new iteration with /pair-process-plan-stories, or running /pair-process-review
to check for open items.
Output Format
Present results as:
PROJECT STATE:
├── PRD: [populated | template]
├── Bootstrap: [complete | incomplete — N/M adoption files populated]
├── Subdomains: [populated | template]
├── Bounded Contexts: [populated | template]
├── PM Tool: [tool name | not configured]
├── Scope: [full backlog | root #ID (subtree) | filter <tag> | root #ID ∩ <tag>]
└── Backlog: [summary of current items — within scope]
RECOMMENDATION: /skill-name
REASON: [one-line explanation]
When --root/--filter yield no work, replace the recommendation with the corresponding Step 0 outcome (root <id> not found → HALT; root <id> is Done → exit; no matching issues → clean exit).
Then ask: "Shall I run /skill-name?"
Graceful Degradation
See graceful degradation (PM tool not accessible → skip Step 3, recommend from adoption files only; adoption files missing → suggest /pair-process-bootstrap as the entry point) for the standard scenarios. Additional cases:
- Argument edge cases (see Step 0):
--root not found → HALT, no action; --root resolves to a Done issue → report and exit; --filter (or the subtree) matches nothing → report no matching issues and exit cleanly (an empty result is not an error).
- If a suggested skill is not installed, tell the user which skill is needed and where to find it.
- If way-of-working.md has no
## State Mapping section, canonical macrostate names are assumed — this is the zero-configuration default, not a degradation.
- If a board can't distinguish
Draft from Ready (no dedicated Ready column), apply the Readiness Fallback (Definition of Ready criteria) rather than treating row 11's condition as unresolvable.
Notes
- This skill is read-only: it inspects state but never modifies files or PM tool data.
- Row order encodes the tie-break (delivery proximity) — see the Tie-break note under the Step 3 table.
- Re-run
/pair-next after completing any skill to get an updated recommendation.
- Full catalog coverage: nearly all of the 38 skills can be suggested — process skills via the cascading checks (Steps 2-3), capability skills via targeted checks (row 7
/pair-capability-checkpoint, rows 12-16 including /pair-capability-grill) or process-skill composition. /pair-capability-publish-pr will be reachable via /pair-process-implement once wired (not yet composed), so /next cannot surface it today.
