---
name: tutorial
description: Interactive 3-minute walkthrough of Manifest for first-time users. Use when a user types `/manifest`, `/manifest tutorial`, `/contract` (with no args), `/contract help`, asks "how do I use this", or otherwise signals they're new and want orientation. Adapts depth based on what the user wants to learn.
---

# Manifest tutorial

You are giving a first-time user a quick orientation. Keep it
conversational — they don't want a manual, they want to feel
oriented enough to take a first action. Aim for under 3 minutes of
their reading time.

## Detect what kind of welcome to give

Read the user's input phrasing:

- **"What is this?" / "/manifest" / "/contract" with no args** →
  Give the 30-second overview, then offer three paths.
- **"How do I use this?" / "tutorial" / "walk me through"** →
  Give the guided walkthrough.
- **"What are the options?" / "commands?" / "help"** → Give the
  reference card.

Default to overview + paths if intent is unclear.

## Always check setup first

Before doing anything else, invoke the **setup-check** skill briefly
to see what's connected. Use the result to tailor the tutorial:

- If everything is connected: proceed normally.
- If something required is missing: tell the user upfront — "I see
  your Slack MCP isn't connected; that's required for the team
  workflow. Want me to walk through what to connect, then come back
  to the tutorial?"
- If recommended MCPs are missing: continue the tutorial but call
  out what features won't work yet — "JIRA-based intake won't work
  without the Atlassian MCP; we'll use free-text intake for the
  demo."

This way the user never gets surprised mid-flow by a missing MCP.

## The 30-second overview

Start with this exact framing (rephrase naturally; don't read it
verbatim):

> Manifest takes a feature idea — a PRD, a JIRA ticket, or a one-line
> description — through a quality-gated pipeline from spec to
> production. Critics check the spec for completeness. An agent
> implements it. The system tracks whether the feature actually
> landed.
>
> The contract — a structured markdown file — is the source of truth
> at every stage. Critics won't let a contract progress until
> required fields are filled. That's what prevents bugs at PRD time
> instead of production time.

Then ask:

> Three ways to learn this:
>
> 1. **🚀 Just try it** — paste a JIRA ticket or describe a feature.
>    I'll walk you through the rest.
> 2. **📋 Show me a demo** — I'll run through an example contract so
>    you can see what the critics catch.
> 3. **📖 Just the reference** — show me the commands and options.

Wait for the user's pick.

**One more option to mention if the user signals they're a dev whose
PM hands off PRDs:** offer Path 4 — `/contract pickup <source>` (the
canonical Spec entry as of 0.18). Phrase it like:

> If your PM writes PRDs in JIRA / Google Docs / Slack and walks
> away, there's a new dev-centric entry point: `/contract pickup
> <source>`. You paste any link; I do the code archaeology and show
> every gap in three buckets (auto-fill, you decide, ask PM). Want
> to try that instead of `/contract new`?

Don't push it on PMs or first-time users — they're better served by
Path 1. Only surface for devs.

## Path 1: Just try it

Ask one question:

> What feature do you want to spec? Either paste a JIRA / Linear /
> Notion link, or describe it in a sentence.

Then route to the **contract-new** skill with their input. Don't ask
the five questions yet — let contract-new handle the intake. As
contract-new runs, narrate in plain language what's happening:

> "Reading your JIRA ticket via the Atlassian MCP..."
> "Extracted the title, description, and 3 platforms from labels..."
> "I need to ask 2 things the ticket didn't cover..."

After contract-new finishes:

> Want me to run the critics now? They'll find what's missing in the
> spec — about 90 seconds.

If yes → invoke contract-verify. After it returns, summarize the
findings in plain language and explain what each severity means:

> The critics found 2 blockers and 4 warnings. Blockers are gaps
> that prevent the contract from progressing — usually missing
> instrumentation or undefined error states. Warnings are things to
> address but not deal-breakers.
>
> Open `.manifest/contracts/<ID>.findings.md` to see them all. The
> typical workflow is: read findings → edit the contract to address
> them → re-run /contract verify until readiness goes green.

End with:

> Once readiness is green, `/contract promote <ID>` freezes the
> revision and starts the SLA timer. That's where implementation
> begins.

## Path 2: Show me a demo

Use the example contract at `examples/EX-001-saved-cards.md`. Walk
through:

1. **The contract format** — open the file and explain the sections:
   frontmatter (typed metadata), Goal, Success Metrics, Behaviors,
   Acceptance Criteria, Diagrams, Out of Scope, Open Questions.
   Spend 20 seconds on why each matters.

2. **The critics** — explain what the relevant critics look for
   in this example contract. Don't list all 9; pick 3-4 high-value
   examples:
   - **edge-cases** would flag "what happens if the user has no
     internet during the card-save"
   - **instrumentation** ensures every behavior has an analytics
     event tied to it
   - **regression** would scan other repos for code that touches
     payment methods
   - the deterministic validator (not a critic) classifies this
     Medium (2 platforms, schema addition) and computes readiness

3. **The gates** — readiness is computed mechanically:
   - 0 open blockers
   - Every behavior has instrumentation
   - Every behavior has at least one AC
   - Confidence ≥ 80%
   No contract progresses without these.

4. **What happens next** — promote freezes a revision and starts
   the SLA timer (24h Small, 72h Medium). The implementer agent
   runs in CI on a PR. Verifier runs Playwright against deployed
   environments. Launch reports run for 28 days.

5. **End with:** "Want to try it on a real feature now? Paste a
   JIRA link or describe what you want to build."

## Path 3: Reference card

Show this compact reference:

```
/contract new <URL or "description">    Author a contract (intake)
/contract verify <ID>                    Run all critics
/contract promote <ID>                   Freeze + start SLA timer

/implement <ID>                          Run implementer agent
/verify-pr <PR>                          Verify PR against contract
/launch <ID> [--day N]                   Manual launch report

/manifest                                This tutorial
/manifest help                           Same as above
```

Then add:

> Input forms `/contract new` accepts:
>
> - `/contract new "Add CSV export"`              ← free text
> - `/contract new https://...atlassian.net/...`  ← JIRA ticket
> - `/contract new https://linear.app/...`        ← Linear issue
> - `/contract new https://notion.so/...`         ← Notion page
> - `/contract new https://github.com/.../issues/N` ← GH issue
> - `/contract new https://figma.com/file/...`    ← Figma file
>
> For deep walkthroughs:
> - `GUIDE.md` — the full how-it-works manual
> - `reference/CONTRACT-FORMAT.md` — contract schema reference

End with:

> Ready? Run `/contract new <your-thing>` to start.

## Edge cases

- **User asks about a specific skill or critic by name** → Read
  that skill's SKILL.md and explain in plain language what it does
  and when it fires.
- **User asks "what about <X tool we don't have>?"** → Be honest.
  If they don't have Amplitude/Firebase Analytics, point at the
  fallback measurement sources in launch-report.
- **User seems confused mid-tutorial** → Stop, ask "what's the part
  that's unclear?" Don't barrel forward.
- **User has already run a command before** (check for
  `.manifest/contracts/` existence) → Skip the welcome framing; go
  straight to whatever they're asking about.

## Anti-patterns

- Don't dump the entire GUIDE.md content. Link to it for depth.
- Don't list all 16 skills with descriptions. Pick the 3-4 the user
  will actually use first.
- Don't pretend the system is magic. It's a structured spec format +
  critics + an agent. Be honest about what it doesn't do (write
  designs, replace product judgment, ship Large features).
- Don't be cheery beyond what's natural. Just be clear and useful.