mk-help

name	mk-help
description	Workflow navigator: scans project state (plans, reviews, tests, git) and recommends the next pipeline step. Use for 'what next?' or 'where am I?'. NOT for complexity routing (mk:scale-routing).

Navigation Help

Answers "What should I do next?" by scanning project state and mapping to the 7-phase pipeline.

How It Works

mk:help is the FORWARD-looking navigator (what to do next). Backward-looking delivery analysis stays with the status skill (project-manager) — this skill never reproduces it.

Collect candidates from ALL scan sources below, then RANK them and emit the top 3 — do NOT stop at the first hit. The rank-1 candidate equals what the old "stop at first actionable hit" behavior would have returned (back-compat); ranks 2–3 are alternates with one-line rationale. This skill is read-only: it reads state, never writes it.

1. Paused Step-File Workflows

Check session-state/*-progress.json for any in-progress step-file workflow.

• Found → "Resume [skill] at step [N]. Run /mk:[skill] to continue."

2. In-Progress Plans

Check tasks/plans/ for plan files without matching review verdicts.

• Plan exists, no tests → "Plan approved. Next: run tester agent (Phase 2 — RED)"
• Plan exists, tests failing → "Tests failing. Next: run developer agent (Phase 3 — GREEN)"
• Plan exists, tests passing, no review → "Tests green. Next: run reviewer agent (Phase 4 — Review)"

3. Pending Reviews

Check tasks/reviews/ for verdict files with WARN or action items.

• WARN verdict → "Review has warnings. Acknowledge and approve for Gate 2, or fix findings."
• FAIL verdict → "Review failed. Fix required changes, then re-run reviewer."

4. Uncommitted Changes

Check git status for staged/unstaged changes.

• Changes exist + review approved → "Ready to ship. Run the ship skill (Phase 5)"
• Changes exist, no review → "Changes detected but no review. Run reviewer first."

5. Clean State

No plans, no reviews, no changes.

• "Everything clean. Options: start a new task with planner, run the retro skill, or ask me anything."

Additional Scan Sources (read after sources 1–5)

ALL four may be absent at rest (e.g. session-state/checkpoints/ does not exist until runtime). Absent file → skip silently; note the skip only under --verbose. Never error on a missing source.

#	Source	Fields to read	Absent-case
6	session-state/checkpoints/checkpoint-latest.json	state.model_tier, progress.plan_path, environment.{git_branch,working_dir_clean,uncommitted_changes}, budget.{estimated_spent_usd,turn_count}, created_at	skip; no checkpoint context
7	session-state/budget-state.json	estimated_cost_usd, turn_count, warnings_emitted (advisory only)	skip; no budget caution
8	session-state/detected-model.json	tier (authoritative current-session tier)	skip; tier unknown
9	tasks/reviews/<slug>-verdict.json	decision, dimensions[].verdict, created_at; .md is prose fallback	use git/plan scan only
10	docs/development-roadmap.md (when present; Type-1 allowlisted)	current phase / milestone progress	skip; tag (CF-C5) if relied on

Model tier: source the current tier from session-state/detected-model.json (written fresh at SessionStart). Do NOT source model_tier from budget-state.json — it has no created_at/session marker and may carry a prior session's tier. Treat budget figures as advisory unless a current-session signal corroborates them.

Staleness: if checkpoint-latest.json created_at is older than 24h, demote its evidence and note the staleness in the rationale.

Ranking Heuristic (deterministic, evidence-cited — no vibes ranking)

Collect candidates from all sources, then rank:

1. Blocked phase or BLOCKED verdict → rank-1 unblock/fix action. A review verdict is blocked when decision === "BLOCKED" — the verdict enum is PASS | PASS_WITH_RISK | BLOCKED; there is NO top-level "FAIL" value. FAIL exists only per-dimension in dimensions[].verdict. Cite the failing dimension(s) in the rationale.
2. In-progress phase (plan phase status: in-progress, or GFM - [ ] checkboxes remaining) → continue action, rationale cites checkbox % (count - [x] vs - [ ]).
3. Approved plan, nothing built → cook action.
4. Budget caution: if warnings_emitted > 0 OR spent ≥ $30, fold a budget caution into the rank-1 rationale (does not by itself create a rank).
5. Clean state → the existing fallback table (start a task / retro / ask).

Each candidate's rationale MUST cite the source file(s) it came from.

For skill suggestions based on task type, see mk:agent-detector (its ../agent-detector/references/lifecycle-routing.md maps task patterns to skills).

State-to-Recommendation Map

Alias: the plan skill routes to mk:plan-creator (slash-command wrapper at .codex/commands/mk/plan.md). Subcommands red-team, validate, archive are handled by the same skill.

State	Pipeline Phase	Recommendation
No plan	Phase 0 → 1	"Start with the plan skill or describe your task"
Existing plan — stress-test	Standalone subcommand	"the plan skill red-team {path} — adversarial review of existing plan"
Existing plan — interview	Standalone subcommand	"the plan skill validate {path} — critical question interview on existing plan"
Completed/cancelled plans	Housekeeping	"the plan skill 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 — write failing tests (RED phase). 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 the review skill — adversarial code review"
Review PASS/WARN	Phase 5	"Run the ship skill — commit, PR, deploy"
Shipped	Phase 6	"Run documenter — update docs, then the retro skill"
Paused workflow	Resume	"Resume [skill] at step [N]"
Mixed state	Clarify	"Multiple items in progress. Which to focus on?"

Specialist Skills (surface when domain matches)

Situation	Skill	When to suggest
Operations, triage, case management, escalation protocols, billing workflows	the decision-framework skill	User asks "how should we handle X cases" or is designing any case-routing system
"Is everything green?", pre-review check, post-implementation validation	the verify skill	After implementation completes, before review, or when user wants a quick health check
API design, endpoint structure, REST/GraphQL conventions	the api-design skill	User is planning backend endpoints or asking about API conventions

Fast Paths (surface these prominently)

Not every task needs the full 7-phase pipeline. Mention these when relevant:

Situation	Fast Path	What it bypasses
Simple bug fix, typo, rename, config tweak	the fix skill	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 the fix skill — bypasses Gate 1 for simple changes.

Small config change? Scale-routing may auto-bypass Gate 1 when blast radius is zero.

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.

Gotchas

• Multiple in-progress plans create ambiguity — ask user which to focus on, don't guess
• session-state/ files from previous sessions may be stale — check timestamps, warn if >24h old
• Git status can be noisy (untracked IDE files) — focus on files in src/, lib/, app/, tests/
• Don't recommend skipping phases — even if the user seems impatient, show the full path
• Fast paths are not loopholes — Gate 2 (review) is NEVER bypassed; security hooks are NEVER skipped
• session-state/checkpoints/ does not exist until runtime — its absence is normal, not an error; skip silently
• budget-state.json is missing at session start — treat budget figures as advisory; never source model tier from it (use detected-model.json)
• Prefer the machine-readable *-verdict.json over the .md prose verdict; a verdict is blocked when decision === "BLOCKED" (never a top-level "FAIL")
• This is the forward-looking navigator — backward-looking delivery status stays with the status skill; do not duplicate it here

Output Format

The ranked next-steps are a JSON-compatible shape (documented here for downstream tooling), rendered as a concise human summary. This skill does NOT emit machine JSON itself — there is no scanner script; the shape documents what the ranking reasons about.

{
  "next_steps": [
    {
      "rank": 1,
      "action": "the cook skill tasks/plans/260610-x/plan.md",
      "priority": "high",
      "rationale": "Plan approved (Gate 1), phase-02 in-progress at 3/7 checkboxes; budget $4.20 of $30",
      "source": ["tasks/plans/260610-x/phase-02-*.md", "session-state/budget-state.json"]
    }
  ],
  "progress": { "plan": "260610-x", "phases_done": 1, "phases_total": 6, "checkbox_pct": 43 }
}

Human rendering (same headings as before — rank-1 is "Recommended Next Step"):

## Status

**Current phase:** [Phase N — Name]
**State:** [brief description]

### Recommended Next Step
[rank-1 action] — [rationale]

### Other Options
- [rank-2 action] — [one-line rationale]
- [rank-3 action] — [one-line rationale]

If --verbose flag: also show full state scan results (plan files, review files, test status, git status) AND which additional sources (6–10) were present vs skipped.