---
name: yad-analysis
description: 'Optional front state 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc/ state (the 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
---

# SDLC — Author Analysis (optional front state 1)

**Goal:** Produce a human-authored, AI-assisted `analysis.md` — the analyst's discovery brief that
shapes the feature **before** the epic — assign its stable `EP-<slug>` ID, and initialise the per-epic
state machine in `.sdlc/`. This is a **front state**: human-authored with AI assist and **never
auto-advances**. When the analysis is drafted, control passes to `yad-review-gate`.

This step is **optional**. When it runs, it is the entry point: it assigns the ID and seeds the
**12-step** chain (`analysis` before `epic`). When it is **skipped**, `yad-epic` does the same
analyst shaping inline and seeds the **10-step** chain — no behaviour change for teams that skip it.

This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
engine (never typed by hand); front steps are locked to `human_approve`.

## Conventions

- `{project-root}` resolves from the project working directory.
- Analysis artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
- Speak in the configured `communication_language`; write documents in `document_output_language`.

## On Activation

### Step 1 — Get the idea
Ask the user for a one-line feature idea if not provided.

**Precondition gate (rail):** analysis is the optional first entry point and seeds state exactly once.
If `.sdlc/state.json` already exists for the target epic, run `yad next EP-<slug> --check analysis`; if it
exits non-zero, **STOP** and point the user at `yad next EP-<slug>` (the epic is past analysis). If it
exits zero, resume analysis for that epic. When no `state.json` exists yet, proceed and seed state.

### Step 2 — Shape the idea (assist: analyst)
Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test the idea in depth: who is the
user, what problem, what already exists, what options are on the table, what signals success, what is
out of scope, and what the recommendation to the epic is. This is the discovery the epic will build on.

### Step 2b — Load existing-code context (make the brain code-aware)
Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **every
connected repo** (the epic's `repos` are not chosen yet), load the lightweight code-map
`{project-root}/.sdlc/code-context/<repo>/code-map.md`. Use it so the analysis's **Current state** and
**Options** reflect what is **already built** — reference existing behaviour rather than re-proposing it.

- **Greenfield-safe:** if `repos.json` is absent or empty, note "no repos connected" and proceed.
- **Staleness:** if a repo's current HEAD (`git -C <path> rev-parse HEAD`) ≠ its registry `syncedHead`,
  warn and suggest `yad repo refresh <repo>` (a human decision — flag and stop, never auto-refresh);
  stamp `code-context: stale` in the frontmatter.
- **Traceability:** record which maps you loaded in the analysis frontmatter `code-context:` field.

### Step 2c — Read the project roadmap (project context, only once discovery is APPROVED)
Consume the project front-zero (`yad-discovery`) **only after its review gate has passed** — never a
draft or in-review roadmap (that would bypass `discovery-review`). Gate on the **state**, not file
existence: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
`currentStep == "discovery-done"`**. When it is, read its `roadmap.md` and sibling `requirements.md`
for the project framing: which phase (MVP / later) this feature belongs to and the requirements it
carries — so the analysis's **Problem / Options / Recommendation** stay consistent with the approved
roadmap. **Optional & non-blocking:** if there is no discovery, or it has not yet reached
`discovery-done`, proceed unchanged — do not consume an unapproved roadmap.

### Step 3 — Generate the Epic ID (engine-assigned, never by hand)
Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
for the project front-zero — never use it for a feature. **The ID is assigned once and
never renamed** — renaming breaks every downstream link (build plan §6b). Check
`{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.

### Step 4 — Open the authoring branch
Open the analysis authoring branch `analysis/EP-<slug>` per the shared procedure
(`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
is not a git work tree), check out the branch if it exists, else create it from the hub's default
branch. Author and commit `analysis.md` on it. This is **distinct** from the bridge's `review/…` branch.

### Step 5 — Write the analysis (assist: analyst)
Write `{project-root}/epics/EP-<slug>/analysis.md` using EXACTLY this template:

```markdown
---
id: EP-<slug>
artifact: analysis
status: draft
owner:
code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps informed this analysis (Step 2b)
---

## Problem
<!-- the problem this feature addresses, who feels it -->

## Users / personas
## Current state (what already exists)
<!-- code-aware, from the code-maps loaded in Step 2b -->

## Options / opportunities
## Risks & constraints
## Success signals
## Recommendation (hand-off to the epic)
<!-- the framing the epic should carry forward -->
```

Fill the body with the user; leave `owner` for the user to set.

### Step 6 — Seed the state machine
Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **12-step** front-state
sequence (analysis before epic), all steps defaulting to `automation: human_approve`, with every
authoring step **locked**. Use this exact shape (see `references/state-schema.md`):

```json
{
  "epicId": "EP-<slug>",
  "createdAt": "<YYYY-MM-DD>",
  "currentStep": "analysis-review",
  "steps": [
    { "id": "analysis",           "type": "author",         "artifact": "analysis.md",      "assistance": "review", "automation": "human_approve", "locked": true,  "status": "done",        "risk_tags": [] },
    { "id": "analysis-review",    "type": "review+approve", "artifact": "analysis.md",      "assistance": "review", "automation": "human_approve", "locked": true,  "status": "in_review",   "risk_tags": [] },
    { "id": "epic",               "type": "author",         "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "epic-review",        "type": "review+approve", "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "architecture",       "type": "author",         "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "architecture-review","type": "review+approve", "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": ["contract"] },
    { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "test-cases",         "type": "author",         "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
    { "id": "test-cases-review",  "type": "review+approve", "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
  ]
}
```

Notes:
- `analysis-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer).
- `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
  (build plan §4): the contract review needs domain owners, not just owner + 1.
- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
  when `stories-review` passes — the epic is already `ready-for-build` by then, so the build half runs
  alongside the tester (see `../yad-epic/references/state-schema.md`).
- Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
  and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
  `[]`, and the `reviews/` directory.
- Commit the seed on the `analysis/EP-<slug>` branch, and cut `review/EP-<slug>/analysis` from it so the
  epic's **first** review PR/MR carries the ledger to the default branch. In bridge mode `ledger-guard`
  exempts a new epic's ledger (creation, not mutation, #162); every later change to it is CI's. See
  `../yad-epic/references/state-schema.md`, "Authoring branches".

### Step 7 — Stop at the gate (do NOT advance)
Report: epic ID, the path to `analysis.md`, and that the next action is **review** via
`yad-review-gate` (base rule: owner + 1 reviewer). **Never mark the analysis-review step approved
here** — only real reviewers do that through the gate. Front states do not auto-advance. When the
analysis gate passes, control moves to `yad-epic`, which reads `analysis.md` as input. When the
hub has a platform, the gate opens a review PR on the hub (via `yad-hub-bridge`) and
`yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
is recorded file-only.

## Reference
- State schema, the two chain shapes, and the authoring-branch procedure:
  `../yad-epic/references/state-schema.md`.
- The epic step that consumes this analysis: `../yad-epic/SKILL.md`.
- Connecting code repos + the code-context the brain reads: `../yad-connect-repos/SKILL.md`.