swain-help

What this skill does

<!-- swain-model-hint: sonnet, effort: medium — default for conceptual explanations; see per-section overrides below -->

# swain-help

Contextual help for the swain skill ecosystem.

## Mode detection

Determine the mode from context:

| Signal | Mode |
|--------|------|
| Invoked from swain-init Phase 4, or user says "just set up swain" / "what now after init" | **Onboarding** |
| User asks a specific question ("how do I...", "what is...", "when should I...") | **Question** |
| User asks for a reference, cheat sheet, commands, or overview | **Reference** |

## Onboarding mode

Present a concise orientation — help the user understand what they just installed without overwhelming them. Adapt tone to context (first-time dev vs experienced engineer).

Present this:

> **Welcome to swain.** Here's how it works:
>
> **The big picture:** Swain manages your project's documentation artifacts (specs, epics, ADRs, etc.) and tracks implementation work — so nothing falls through the cracks between sessions.
>
> **Three things to know:**
>
> 1. **`/swain` is your entry point.** It routes to the right sub-skill automatically. You can also call skills directly (`/swain-design`, `/swain-do`, etc.).
>
> 2. **Design before you build.** When you want to implement something, start with `/swain` to create a spec. Swain enforces a "plan before code" workflow — it creates tracked tasks before implementation begins.
>
> 3. **Health checks are automatic.** `/swain-doctor` runs at session start to ensure routing rules are in place and `.tickets/` is healthy. You don't need to think about it.
>
> **Common starting points:**
> - "I want to plan a new feature" → creates an Epic or Spec
> - "Write a spec for X" → creates an Agent Spec
> - "What should I work on next?" → checks your task backlog
> - "File a bug" → creates a Spec with `type: bug`
> - "Let's release" → version bump + changelog
>
> **Need more?** Ask me anything about swain, or say `/swain help reference` for a full cheat sheet.

Then stop. Let the user ask follow-up questions — don't dump everything at once.

## Question mode

Answer the user's specific question using your knowledge of swain. If you need details beyond what's in this skill, read the relevant reference:

| Topic | Where to look |
|-------|---------------|
| Artifact types, phases, relationships | `references/quick-ref.md` — Artifacts section |
| Commands and invocations | `references/quick-ref.md` — Commands section |
| Step-by-step walkthroughs | `references/workflows.md` |
| Artifact definitions and templates | sibling skill `swain-design/references/<type>-definition.md` |
| tk (ticket) CLI reference | sibling skill `swain-do/references/tk-cheatsheet.md` |
| Troubleshooting | sibling skill `swain-design/references/troubleshooting.md` |

Guidelines for answering:

- **Be concise.** Answer the question, don't dump the entire reference.
- **Use examples** when they clarify — "You'd say `/swain create a spec for auth token rotation`".
- **Hand off when appropriate.** If the user's question is really a request to *do* something (e.g., "how do I create a spec?" followed by "ok do it"), invoke the relevant skill directly via the Skill tool. Explain what you're doing: "I'll hand this off to swain-design."
- **Admit gaps.** If something isn't covered, say so rather than inventing swain features.

<!-- swain-model-hint: haiku, effort: low — reference lookups are simple file reads -->
## Reference mode

When the user wants an overview or cheat sheet, read `references/quick-ref.md` and present the relevant section. If they want "everything", present the full quick reference but note it's dense.

For workflow walkthroughs, read `references/workflows.md`.