---
name: haoman-guided-session
description: >-
  Starts and continues a Haoman guided discussion via MCP so identity documents
  and project knowledge-base RAG shape the conversation. Use when the user wants
  to think through ideas with Haoman, start a guided session, or discuss the
  project without implementing yet. Requires Haoman MCP.
---

# Haoman guided session

Run a **Guided Discussion** through Haoman MCP. You are the bridge between the user and Haoman. Haoman holds identity and KB; you do not paste them into local context as a substitute.

## What Haoman already injects

On every `start_discussion` / `continue_discussion` turn with `type: "guided"`, Haoman:

- Loads level-1 **identity documents** (Concept, Financial Philosophy, Structural Constraints, Test Framework) into the discussion system prompt
- Resolves and injects the project's canonical **Effective Operating Context**
  when an Operating Model is attached; candidate tenets are excluded
- Runs **project-scoped KB RAG** (embeddings) against the latest user message and injects matching pages into that turn

You do **not** need to call `get_identity_documents` for Haoman to use them. Optional local reads are only for your own orientation — never invent identity.

## Prerequisites

- Haoman MCP connected (`list_projects`, `start_discussion`, `continue_discussion`)
- If missing, ask the user to install or reconnect the Haoman plugin. If
  unauthorized, ask them to reconnect Haoman and complete the browser sign-in.
  Do not ask them to paste credentials into chat.

## Workflow

```
Guided session:
- [ ] 1. Resolve projectId
- [ ] 2. Refresh local Haoman context cache
- [ ] 3. Start or resume guided discussion
- [ ] 4. Relay Haoman ↔ user (loop)
- [ ] 5. Stop when the user ends or switches intent
```

### 1. Resolve project

1. Call `list_projects`.
2. If one project, use it. If several, match the name they gave or ask which project.
3. Keep `projectId` for the session.

### 2. Refresh local Haoman context cache

Follow `shared/context-cache.md` (bundled with this skill) before the discussion loop:

1. Call `get_identity_documents` and `get_effective_operating_context` for the
   resolved `projectId`.
2. If this checkout matches a Coding Repo, resolve it with `list_coding_repos`
   and also call `get_effective_technical_context`.
3. Compare hashes to `haoman/context/cache-manifest.json`. Rewrite
   `.cursor/rules/haoman-context.mdc` and `haoman/context/*` only when stale or
   missing.
4. Keep using MCP discussion tools for thinking. The local mdc is directional
   orientation for the checkout, not a substitute for Haoman’s turn injection.

If refresh tools fail, disclose that the local cache was not updated, then
continue the guided discussion if MCP discussion tools still work.

### 3. Start or resume

**New session** — call `start_discussion`:

- `projectId`
- `type`: `"guided"`
- `title`: short label (optional)
- `message`: the user's opening idea in their words, plus:

```text
This is a Guided Discussion. Stay in thinking-partner mode.
Use the project's identity and knowledge base as you normally would.
Do not write application code. Do not produce implementation plans unless I ask.
```

Keep the returned `discussionId`. Follow `shared/discussion-turn.md` for the opening reply and any `savedDocuments`.

**Resume** — if they already have a guided discussion id, skip create and use `continue_discussion` with that id. Or call `list_discussions` with `type: "guided"` and ask which one.

### 4. Discussion loop

For each user turn:

1. Send their message with `continue_discussion` (`discussionId` + `message`).
2. Follow `shared/discussion-turn.md` for the reply and any `savedDocuments`.
3. Show Haoman's reply plainly (do not rewrite it into your own identity advice).
4. **Materialize saved notes locally** — when `start_discussion` / `continue_discussion` returns a non-empty `savedDocuments` array, for each entry immediately write `content` to `suggestedLocalPath` (create parent dirs as needed). Tell the user the path(s). Do not wait until the session ends.
5. Ask follow-ups only if the user expects you to; otherwise wait for their next message.
6. Do **not** implement product code while this skill is the active mode, unless they explicitly leave guided discussion and ask to build.

Reuse the same `discussionId`. Do not start a new discussion every turn.

### 5. Optional helpers

| Tool | When |
|------|------|
| `get_discussion` | User wants transcript / prior turns |
| `get_discussion_documents` | Backfill older notes (`includeContent: true`); each item includes `suggestedLocalPath` |
| `get_identity_documents` | You need a local peek; Haoman already has them |
| `list_discussion_types` | Confirm `guided` is available |

## Anti-patterns

- Pasting Concept / KB into Codex as a fake substitute for Haoman
- Answering “as Haoman” from local guesswork without calling MCP
- Starting `guided_prototype` or build types when the user asked for guided thinking
- Creating a new discussion every message
- Silently switching into implementation during a guided session
- Inventing a Haoman reply when a turn errors or times out
- Resending the same message after a failed turn without the user asking
- Leaving `savedDocuments` only in chat — always write them to `suggestedLocalPath` when present