Navigation assistant — scans project state (plans, reviews, tests, git, checkpoint/budget/model/verdict sources) and ranks the top next steps in the 7-phase pipeline.


Source	`.claude/skills/help/SKILL.md`
Owner	`research`
Runtime	`claude-code`
Risk	medium

What This Skill Does

Answers "What should I do next?" by scanning project state and mapping to the 7-phase pipeline. Use at session start, after interruption, or when uncertain about the next step.

When to Use

"what should I do next?", "where am I?", "help"
At session start to orient
After an interruption to resume
When the pipeline state is ambiguous

Explicit: /mk:help [--verbose]

NOT for: Domain complexity routing (see mk:scale-routing), skill discovery (skill descriptions handle that automatically), or task-type-to-skill suggestions (see mk:agent-detector).

Collects candidates from all sources below, then ranks them and emits a top-3 of next steps with rationale — it does not stop at the first hit. The rank-1 step equals the old single recommendation (back-compatible); ranks 2–3 are alternates. The skill is read-only.

Base sources:

Paused Step-File Workflows — checks session-state/*-progress.json for in-progress step-file skills.
In-Progress Plans — checks tasks/plans/ for plans without matching review verdicts, maps to Phase 2/3/4.
Pending Reviews — checks tasks/reviews/ for WARN or FAIL verdicts needing action.
Uncommitted Changes — checks git status for staged/unstaged changes + review approval status.
Clean State — no plans, no reviews, no changes → suggests starting new task or running retro.

Additional sources (each skipped silently when absent):

Checkpoint state — session-state/checkpoints/checkpoint-latest.json (model tier, active plan, branch, budget; staleness demoted past 24h via created_at).
Budget state — session-state/budget-state.json (cost, turn count, warnings) — advisory only.
Detected model — session-state/detected-model.json (authoritative current-session tier).
Review verdicts — tasks/reviews/<slug>-verdict.json (decision, per-dimension verdicts).
Roadmap — docs/development-roadmap.md when present.

A review is blocked when decision === "BLOCKED" — the verdict enum is PASS | PASS_WITH_RISK | BLOCKED; FAIL exists only per-dimension. The ranked next-steps are documented as a JSON-compatible shape and rendered as a concise human summary. Backward-looking delivery status stays with /mk:status.

State-to-Recommendation Map

State	Pipeline Phase	Recommendation
No plan	Phase 0 → 1	"Start with `/mk:plan` or describe your task"
Existing plan — stress-test	Standalone subcommand	"`/mk:plan red-team {path}` — adversarial review of existing plan"
Existing plan — interview	Standalone subcommand	"`/mk:plan validate {path}` — critical question interview on existing plan"
Completed/cancelled plans	Housekeeping	"`/mk:plan archive` — archive completed or cancelled plans"
Plan approved, no tests	Phase 2 (TDD mode only)	"In TDD mode (`--tdd` / `MEOWKIT_TDD=1`): run tester agent (RED). In default mode: skip Phase 2; run developer directly"
Tests written, failing	Phase 3	"Run developer agent — implement to pass tests (GREEN)"
Tests passing, no review	Phase 4	"Run `/mk:review` — adversarial code review"
Review PASS/WARN	Phase 5	"Run `/mk:ship` — commit, PR, deploy"
Shipped	Phase 6	"Run documenter — update docs, then `/mk:retro`"
Paused workflow	Resume	"Resume [skill] at step [N]"
Mixed state	Clarify	"Multiple items in progress. Which to focus on?"

Specialist Skills

These surface when the user's domain matches:

Situation	Skill	When to suggest
Operations, triage, case management, escalation protocols, billing workflows	`/mk:decision-framework`	User asks "how should we handle X cases" or is designing any case-routing system
"Is everything green?", pre-review check, post-implementation validation	`/mk:verify`	After implementation completes, before review, or when user wants a quick health check
API contract design or review — interface shape, error semantics, compatibility, pagination	`/mk:api-design-principles`	User is authoring or reviewing what an API promises, not how it runs
Backend change end to end — handler, service, integration, webhook, job	`/mk:backend-development`	User is changing backend behavior and needs contract, data, and auth owners coordinated
Schema, migration, query, index, or ORM data-access boundary	`/mk:database`	User is modelling, evolving, or querying data
Infrastructure, containers, CI/CD, deployment safety, rollback	`/mk:devops`	User is changing how the system is built, configured, or delivered

Fast Paths

Not every task needs the full 7-phase pipeline:

Situation	Fast Path	What it bypasses
Simple bug fix, typo, rename, config tweak	`/mk:fix`	Gate 1 (plan approval) — scope is the plan
Task flagged as `one-shot` by scale-routing	Auto Gate 1 bypass	Gate 1 — zero blast radius confirmed
Rapid iteration / spike work	`MEOWKIT_HOOK_PROFILE=fast`	post-write scan, pre-ship, pre-task-check, TDD check

Quick fix? Use /mk:fix — bypasses Gate 1 for simple changes. Hook profiles: Set MEOWKIT_HOOK_PROFILE=fast for rapid iteration (skips non-critical hooks). Set MEOWKIT_HOOK_PROFILE=strict to enable ALL hooks including post-session capture.

Arguments

Argument	Effect
(none)	Ranked top-3 next steps (rank-1 is the recommended step)
`--verbose`	Full state scan results: plan/review files, test + git status, and which additional sources (6–10) were present vs skipped

Example Prompt

I just came back to this project after a break. What should I do next? Show me the full state scan.

mk:help