Mk Help

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.

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.

Specialist Skills (surface when domain matches)

Fast Paths (surface these prominently)

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

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.