--- name: yad-analysis description: 'Optional Shape step 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP- 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 Shape step 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-` ID, and initialise the per-epic state machine in `.sdlc/`. This is a **Shape step**: 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); every Shape step starts at `advance: human`. A review gate is always human; only the team can set a Shape author step to auto (`yad dial`, recorded in `.sdlc/automation.json`; nothing acts on it yet). ## Conventions - `{project-root}` resolves from the project working directory. - Analysis artifacts live under `{project-root}/epics/EP-/` (build plan §6). - Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; 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):** the chain is seeded exactly once, and this skill is no longer the only thing that can have done it — `yad epic new --profile analysis-first` seeds the same 12-step chain from the CLI. So the question is whether `.sdlc/state.json` exists, not who wrote it: - **A chain already exists** — run `yad next EP- --check analysis`. If it exits non-zero, **STOP** and point the user at `yad next EP-` (the epic is past analysis). If it exits zero, resume analysis for that epic and **skip Step 6** (the chain is already there — re-seeding is refused anyway). - **No `state.json`** — this is the entry point. Run Step 6 to seed the chain. **Step 6b runs on both paths.** It is what closes the authoring step and opens its gate, and nothing else does it. ### Step 2 — Shape the idea (assist: analyst) Adopt the **analyst** lens 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//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 rev-parse HEAD`) ≠ its registry `syncedHead`, warn and suggest `yad repo refresh ` (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 Foundation (product context, only once it is APPROVED) Consume the Product level (written by `yad-discovery`) **only after its review gate has passed** — never a draft or in-review one (that would bypass its gate). Gate on the **state**, not file existence: - **The Foundation:** read `{project-root}/foundation/.sdlc/state.json` and proceed **only when `currentStep == "foundation-done"`**. Then read `foundation/purpose.md`, `scope.md`, `mvp.md` and `roadmap.md` for the product framing. - **The old spelling**, only when there is no Foundation: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when `currentStep == "discovery-done"`**. Then read its `roadmap.md` and sibling `requirements.md`. Use it for: which phase (MVP / later) this feature belongs to, what the product explicitly is **not**, and the requirements it carries — so the analysis's **Problem / Options / Recommendation** stay consistent with the approved product. **Optional & non-blocking:** if there is no product level, or it has not passed its gate yet, proceed unchanged — do not consume an unapproved one. (`yad next` reports feature work that goes ahead of an unapproved Foundation; it never blocks it.) ### Step 3 — Generate the Epic ID (engine-assigned, never by hand) *(Skip when `state.json` already exists — the id was assigned by whatever seeded the chain.)* Derive `EP-` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea (e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-foundation` and `EP-discovery` are **reserved** for the Product level — never use either 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. When the Foundation's `roadmap.md` has a row for this feature, prefer that row's **proposed epic id**, so `yad foundation status` can match the feature to its epic. ### Step 4 — Open the authoring branch Open the analysis authoring branch `analysis/EP-` per the shared procedure (`../yad-epic/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 Product's default branch. Author `analysis.md` on it, and end the step with `yad fold EP- analysis` — the one commit the step keeps (E44). This is **distinct** from the verified ledger's `review/…` branch. ### Step 5 — Write the analysis (assist: analyst) Write `{project-root}/epics/EP-/analysis.md` using EXACTLY this template: ```markdown --- id: EP- artifact: analysis status: draft owner: code-context: { repos: [], loaded: } # which code-maps informed this analysis (Step 2b) --- ## Problem ## Users / personas ## Current state (what already exists) ## Options / opportunities ## Risks & constraints ## Success signals ## Recommendation (hand-off to the epic) ``` Fill the body with the user; leave `owner` for the user to set. ### Step 6 — Seed the state machine — only when nothing is seeded *(Skip when `state.json` already exists — `yad epic new --profile analysis-first` seeded it. Go to Step 6b. Re-seeding would overwrite a ledger, and in verified mode that is the mutation `ledger-guard` rejects.)* **Run the engine. Do not hand-write the chain.** ```bash yad epic new EP- --profile analysis-first --type yad epic new EP- --profile spike --type # a timeboxed investigation ``` That writes `{project-root}/epics/EP-/.sdlc/state.json`, the empty `approvals.json` and `comments.json`, and the `reviews/` directory. With `--profile analysis-first` the chain is the full **12-step** route (`analysis` before `epic`). Every step starts at `advance: human`; `analysis` is open and the rest are `todo`. The chain comes from the step catalogue and the lifecycle profile in the engine (`../yad-epic/references/state-schema.md`), so there is one definition of it and no copy here to drift from it. **Ask whether this is a spike before you seed.** `analysis-first` is the right answer when the analysis is the front of a real feature. When the work IS the investigation — a timeboxed question whose output is a finding and a throwaway prototype — `--profile spike` seeds a **6-step** lane instead: `analysis → analysis-review → epic → epic-review → stories → stories-review`, with no architecture, UI-design or test-case steps. `analysis` is still the open first step either way, so every step below this one is unchanged. A spike has **no architecture gate, so no `contract.md` and no lock**, and no step on it is optional — `yad skip` is refused. **Choose the route before you seed, because the choice is final:** there is no re-seed. If the investigation concludes that the shared cross-repo surface has to move, the follow-up belongs on `classic` — the spike records the finding, and a NEW epic builds it. It writes no `analysis.md`, no branch and no commit, and it refuses an epic that already has a `state.json`. There is no `epic.md` at this point, so pass `--type` (it defaults to `feature`). Notes: - **Then advance the authoring step.** The seed leaves `analysis` open, which is truthful: the command runs before the artifact exists. Closing it is Step 6b's job, and on the local path `yad gate open` does it — so after writing `analysis.md`, take Step 6b. - `analysis-review` carries no `risk_tags` — it is the **base** rule (1 distinct approver, who should not be the author). The catalogue sets that; there is nothing to type. - `architecture-review` carries `risk_tags: ["contract"]` by default (build plan §4): the tag raises the step's full approver count to 3 (base 1 + contract risk 2). Only the base holds the gate; the risk step is advisory, reported as a shortfall against the count capped at the active people less one (E72). - `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `todo` and open when `stories-review` passes — the epic is already `ready-for-build` by then, so Build runs alongside the tester (see `../yad-epic/references/state-schema.md`). - Commit the seed on the `analysis/EP-` branch, and cut `review/EP-/analysis` from it so the epic's **first** review PR/MR carries the ledger to the default branch. In verified 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". - **No UI, on a verified Product?** The analysis review PR is this epic's first, so until it merges is the only time `yad skip` can write the ledger. If the idea clearly has no user-facing surface, offer `yad skip EP- ui-design --reason ""` now; after that PR merges, CI owns `state.json` and the skip is refused. On a local ledger there is no hurry: `yad-ui` offers the same skip later. ### Step 6b — Open the analysis review gate *(**Always run this**, on both entry modes. The chain is seeded by now either way — by `yad epic new` in Step 6, or by `yad epic new` before this skill was invoked — and `analysis.md` is written. This is the step that closes the authoring step and opens its gate.)* **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name): **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present. **verified mode — do NOT write `state.json`.** The ledger is CI-owned and advancing a step is a mutation: `ledger-guard` rejects any non-bot commit that changes one, and `yad gate ci --merged` performs the whole transition when the review PR merges. **Do not EDIT the ledger — but do COMMIT it when it is untracked.** `yad fold EP- analysis` does exactly this while the epic is new (no `state.json` in HEAD): it takes the artifact, the new ledger files and any new person-written `.sdlc/` file of the seed, and leaves every other ledger change to CI. Those are two different acts. Commit `analysis.md`, and also `.sdlc/state.json`, `.sdlc/approvals.json` and `.sdlc/comments.json` when `git status` shows them **untracked** — an engine-seeded ledger has never been reviewed, so it is still off the base ref and `ledger-guard` exempts it (creation, not mutation, #162). It rides this epic's first review PR exactly as a Step 6 seed does. Leave their contents alone. **Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.** `yad gate open analysis.md` marks `analysis-review` `in_review`, closes `analysis` as `done`, and moves `currentStep` to the gate — the same transition, from the one function that owns it (`markInReview`, `cli/epic-state.mjs`). `yad-review-gate action: open` runs that command; hand off to it rather than editing the ledger here. **With no platform configured** it writes the ledger and simply opens no PR, so this works offline. **With a platform** the `review/EP-/analysis` branch must already be **on origin** — the command refuses and writes nothing otherwise. Cut it from the authoring branch and push it before handing off (`yad open-pr` does both, then delegates). Do **not** hand-edit `state.json`, do **not** re-seed, and do **not** touch `approvals.json` — only real reviewers approve, through the gate. ### 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: 1 distinct approver, who should not be the author). **Never mark the analysis-review step approved here** — only real reviewers do that through the gate. Shape steps do not auto-advance. When the analysis gate passes, control moves to `yad-epic`, which reads `analysis.md` as input. When the Product has a platform, the gate opens a review PR on the Product (via `yad-product-bridge`) and `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review is recorded local. ## 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`.