---
name: help-me
description: Dynamic next-step navigator — evaluates project state, checks skill catalog, codebase/doc graphs, and provides a tailored navigation report with recommended slash commands.
---

## What this skill does

Acts as your intelligent co-pilot. When you feel stuck, uncertain about the next step, or need to check project health, `help-me` performs a full diagnostic and tells you exactly what to do next.

It answers: **"What should I do right now?"**

## When to use

- `"help me"` or `/help-me` — when unsure of the next step
- `"/help-me [query]"` — targeted question about a specific phase or skill
- After a long pause between sessions — fast re-orientation
- Before running any skill — check if prerequisites are met

## Workflow

### Step 0: Empty-Project Fast Path

**Run this check first — before any agent or script call.**

Check whether BOTH files exist:
- `artifacts/output/pipeline-state.json`
- `artifacts/memory/project-context.md`

If either is missing, the project is uninitialized. **Do not call `@memory-controller`, do not run `orchestrator_state.js`, do not run any graph generator.** Two paths from here:

**Path A — User asked a specific question** (e.g., "what skills are available?", "how does vespyr work?", "what's the difference between /design and /develop?"):

- Read `.agents/skills/help-me/skills-catalog.json` for the skill index
- Read `.agents/AGENTS.md` if you need framework context (phases, agents, guardrails)
- Answer their question directly, citing the relevant skills/agents by name
- If the question implies starting a project, close with `/validate-idea` or `/squad` as the natural next step
- Keep the response tight — they asked one thing, not a tour

**Path B — User typed bare `/help-me` with no question** (or a generic "what should I do?"):

Respond with this exact short message:

> This looks like a fresh project — no pipeline state yet.
>
> - **To start a project:** run `/validate-idea` (pressure-test a concept) or `/squad` (initialize the team preset)
> - **To learn the framework:** ask *"what skills are available"*, *"how does vespyr work"*, or *"what's the difference between /design and /develop"* — I'll walk you through it
> - **To load existing state:** run `/status` if you have specs or a codebase already

Stop here. Do not enumerate skills, do not call any other agent.

### Step 1: Load Project State & Identity

1. Load memory context:
   ```
   @memory-controller load help-me [next step navigation]
   ```
2. Read `artifacts/memory/project-context.md` and `artifacts/output/pipeline-state.json` to determine:
   - User Nickname (under `## Identity` in `project-context.md`)
   - Project Name, Type, and Active Squad
   - Current Phase (Validation / Exploration / Design / Development)
   - Operation Mode (`autonomous` or `semi-autonomous`)
   - Active Blockers & Open Change Requests (CRs)

### Step 2: Load Skill Catalog & Agent Roster

Read `.agents/skills/help-me/skills-catalog.json` — the compiled index containing:
- `skills`: available skills with their names, descriptions, prerequisites, outputs, and key agents.
- `agents`: the roster mapping agent handles (e.g. `founder`, `architect`) to their human names and descriptions.

> This file is auto-generated by `node .agents/scripts/compile_skills.js`. Re-run if it is stale.

### Step 2.5: Run Active Diagnostics

1. **Git Status Check**:
   Run via `@executor`:
   ```bash
   git branch --show-current
   git status --porcelain
   ```
   Determine if there are modified files (especially in `src/` or `tests/`) or uncommitted work.
2. **Last Session Summary**:
   Check the `history` array in `pipeline-state.json` and run via `@executor`:
   ```bash
   git log -n 3 --oneline
   ```
   Analyze these to synthesize what was done in the last session.
3. **Memory Health Check**:
   Verify if the following files exist and are populated:
   - `artifacts/memory/project-context.md`
   - `artifacts/memory/active-decisions.md`
   - `artifacts/memory/lessons-learned.md`

### Step 3: Check Artifact Readiness & Determine Next Action

Query the pipeline state engine via the CLI to find the exact next task and status:

1. Run via `@executor`:
   ```bash
   node .agents/scripts/orchestrator_state.js next
   ```
2. Parse the state engine's returning JSON next action to direct the user:
   - **`resolve-cr`**: Point out the specific open Change Request (CR) ID, sender, receiver, and target file. Suggest resolving this CR before moving forward.
   - **`resolve-blocker`**: List the active blockers and the assigned owners.
   - **`generate-artifacts`**: Identify precisely which required artifacts are missing for the current phase, cross-referencing against the skill catalog's prerequisites, and recommend the exact skill to run.
   - **`advance-phase`**: Suggest the exact command to transition the pipeline to the next phase.

### Step 4: Optional — Structural Graph Check

If the user query touches codebase or document traceability:
- **Codebase graph:** Run `node .agents/scripts/ensure_graph.js code` via `@executor` (self-healing wrapper; no-op if fresh)
- **Document graph:** Run `node .agents/scripts/ensure_graph.js doc` via `@executor` (self-healing wrapper; no-op if fresh)
- Report any stale or missing nodes

### Step 5: Respond (Structured Format)

Structure your response to the user as follows:

1. **Greeting & Project Context**:
   - Greet the user by their preferred nickname (e.g., "Hi Christian!").
   - Summarize the current project state: Name, active branch, active phase, and squad.
2. **Recent Activity**:
   - Briefly summarize what was worked on recently (based on recent git commits or pipeline history).
3. **Git Status & Uncommitted Work**:
   - Report any uncommitted modifications or new files.
   - Propose logical solutions based on the modified files (e.g., *"I noticed you modified some code files; you should run `/test` to verify or `/review` to audit changes"*).
4. **Active Squad Roster**:
   - Identify the active squad in `project-context.md`.
   - List the squad members, translating their handles to their human names using the agent roster (e.g., `Elena (@founder)`, `Sarah (@product-manager)`, `Vera (@architect)`).
   - Format this as a neat Markdown table:
     | Agent | Human Name | Responsibility |
     | :--- | :--- | :--- |
     | `@architect` | Vera | Designs system architecture... |
5. **Next Step & Detailed Solution**:
   - Provide a detailed explanation of the next step returned by `orchestrator_state.js next`.
   - **Blockers / CRs**: Explain what the issue or change request is, who is involved, and exactly how to resolve it step-by-step.
   - **Missing Artifacts**: Explain what the missing artifact is, what its purpose is, and which agent (using their human name) is responsible for creating it.
   - Provide a clear **Call to Action** with the exact command to run.
6. **Memory Health Status**:
   - Report if any core memory files are missing or require updates.
7. **Phase Quick Reference (Cheat Sheet)**:
   - Provide realistic examples of commands commonly used in the current phase. For example:
     - **Validation Phase**: `/validate-idea "idea"` or `/validate-game-idea "idea"`
     - **Exploration Phase**: `/explore-idea`
     - **Design Phase**: `/design`
     - **Development Phase**: `/develop`, `/review`, `/test` or `/kanban`