---
name: prd-add
effort: medium
description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
---

# /prd-add — Change Request for Active PRD Sessions

Add a new requirement to an existing PRD session. Uses the ICIAS protocol
(Impact-Confidence-Artifact Stakes) to determine which phases and artifacts
need revision, then executes only the affected ones.

## Project Context

**Reads from `baldart.config.yml`:** `paths.prd_dir`, `paths.design_system`.
**Gated by features:** `features.has_prd_workflow` (REFUSES to run when `false`), `features.has_design_system` (Rule 9 BLOCKING when `true`).
**Overlay:** loads `.baldart/overlays/prd-add.md` if present — and inherits the prd overlay's terminology + design-system reads (since prd-add operates on /prd's artifacts).
**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


---

## TRIGGER MODES

### 1. Manual invocation
User types `/prd-add <description>` or `/prd-add` (then describes the change).

### 2. Auto-trigger from /prd discovery
During `/prd` Step 2 (Discovery Question Loop), if the user's answer reveals
a new sub-feature or structural requirement NOT covered by the original feature
description, the `/prd` skill invokes `/prd-add` automatically.

Detection signal: the user's answer introduces NEW entities (endpoints, collections,
pages, roles, flows) that were not part of the original feature scope.

**IMPORTANT — auto-trigger target:** `/prd`'s dispatch table row `2→CR` points to
`references/prd-add-phase.md` (a legacy stub). When executing a Change Request,
**this SKILL.md is the canonical spec** — use it, not the stub. The stub lacks the
worktree registry scan (Step 0), the `WORKING_DIRECTORY` discipline, and the
side-effect rules; executing via the stub will operate on the main repo and break
session isolation. Always load and follow this file (`framework/.claude/skills/prd-add/SKILL.md`).

---

## EXECUTION MODEL

Sequential, single-turn analysis + selective multi-turn re-execution.

| Step | Phase | Description |
|------|-------|-------------|
| 0 | Session Locate | Find active PRD state file |
| 1 | Intake | Capture and classify change request |
| 2 | Impact Analysis | ICIAS protocol (3 phases) |
| 3 | Verdict | Present impact matrix, ask confirmation |
| 4 | Selective Execution | Re-run only PATCH/REDO phases |
| 5 | Delta Commit | Commit changes with `[PRD-ADD]` prefix |

---

## HARD RULES

1. NEVER start from scratch. Always build on the existing PRD session.
2. Read the state file and PRD before any analysis.
3. Follow ICIAS protocol exactly — read [impact-analysis.md](../prd/references/impact-analysis.md) (canonical SSOT; see B4).
4. Present verdict BEFORE executing changes. Wait for user confirmation.
5. When re-running phases, follow the SAME reference files as `/prd` (discovery-phase.md, etc.).
6. Update the state file with a `## Change Requests` section tracking all CR history.
7. Commit with format: `[PRD-ADD] <slug>: <brief CR description>`
8. **Every message MUST end with the CR Progress Bar.**
9. **Design System SSOT re-validation (UI-touching CRs).** When `features.has_design_system: true` AND the change request introduces, modifies, or removes any UI surface (new page, component, layout, flow, or visual state), you MUST re-validate against `${paths.design_system}/INDEX.md` (component index + authority matrix + Quick rules MUST). The ICIAS impact analysis MUST include design-system scope as a dimension: check whether affected UI maps to existing components in `${paths.design_system}/components/<Name>.md` (PATCH = reuse existing) or introduces a new pattern (REDO = propose new component doc and route through DS ownership). When `features.multi_tenant_theming: true`, themed surfaces MUST be re-checked against the project's theming pattern doc; motion changes MUST reference the project's motion pattern doc (both listed in `.baldart/overlays/prd.md`). Cite consulted DS docs in the updated PRD's Canonical Sources section.

---

## Step 0 — Session Locate

**Since v3.22.0, active PRD sessions live inside docs worktrees** created by
`/prd` Step 1 (HARD RULE 17 of `/prd` SKILL.md). The main repo's
`${paths.prd_dir}/sessions/` may be EMPTY even when there are active sessions
— each one lives at `<docs-worktree>/${paths.prd_dir}/sessions/`. This step
must scan the worktree registry FIRST, then fall back to the main repo for
legacy sessions.

1. **Read `.worktrees/registry.json` from the main repo root.** Filter entries
   with `kind: "docs"`. For each, list state files at
   `<entry.path>/${paths.prd_dir}/sessions/*.md` and read the first line of
   each to extract `status:` (or scan for `Status:` line — depends on
   state-template.md format). Collect every state with `status != "completed"`
   together with its `WORKING_DIRECTORY` = `<entry.path>` and `branch` =
   `<entry.branch>`.

   **Registry absent or entry missing with worktree dir present:** If
   `.worktrees/registry.json` does not exist, OR it is parseable but contains
   zero `kind: "docs"` entries, AND a directory matching
   `.worktrees/docs-*` exists on disk: surface a diagnostic —
   `REGISTRY_MISMATCH: .worktrees/registry.json is absent or has no docs entries
   but a docs worktree directory exists on disk. Running a CR from the main repo
   would break session isolation.` — then HALT and ask the user to manually
   provide the docs worktree path before continuing. Do NOT silently fall through
   to the legacy scan in this case.

2. **Also list `${paths.prd_dir}/sessions/` on the main repo** (legacy
   pre-v3.22.0 sessions). Collect any state files there as candidates with
   `WORKING_DIRECTORY` = main repo root.
   This fallback only applies when Step 1 produced zero registry entries AND no
   on-disk docs-worktree directory was detected.

3. Merge the two lists. Behavior:
   - **Exactly ONE active session**: use it. **Write `WORKING_DIRECTORY` and
     `BRANCH` to the state file tracker under `## CR Session`** before proceeding
     — every later consumer reads them from there. These variables must survive
     context compaction; every step that uses them MUST begin with a
     presence-and-non-empty guard: if either is absent or empty in the tracker,
     HALT with `MISSING_VAR: WORKING_DIRECTORY / BRANCH not found in state file`.
   - **Multiple active sessions**: ask the user which one, surfacing
     `WORKING_DIRECTORY` (worktree path or "main repo") in the choice list so
     they know where the CR will be written. Write chosen values to tracker.
   - **Zero sessions**: inform user, suggest `/prd` instead.

4. **`cd "$WORKING_DIRECTORY"`** before any read or write — every subsequent
   step in this skill (intake → impact analysis → selective execution → delta
   commit) MUST use absolute paths rooted at `$WORKING_DIRECTORY`. Note: Claude
   Code's Read/Write/Edit tools require absolute paths and do not honor a working
   directory state set by a prior shell `cd`; always concatenate
   `$WORKING_DIRECTORY/<relative-path>` explicitly for every tool call.

5. Read the state file AND the PRD document (if exists), both resolved under
   `$WORKING_DIRECTORY`.

6. **Worktree-mode side effects for the rest of the skill:**
   - Step 5 "Delta Commit" stages files inside the worktree and commits with
     `git -C "$WORKING_DIRECTORY" commit`. NEVER `git add` on the main repo.
   - If `prd-card-writer` is re-invoked in Step 4 (Backlog Cards REDO), pass
     `WORKING_DIRECTORY: $WORKING_DIRECTORY` in the prompt — same convention
     as backlog-phase.md (see `framework/.claude/agents/prd-card-writer.md` §
     "Working Directory").
   - If `ui-design` is re-invoked in Step 4 (UI Design REDO), pass
     `WORKING_DIRECTORY=$WORKING_DIRECTORY` as args — same convention as
     ui-design-phase.md.
   - The delta commit is NOT auto-merged. Document the new branch tip in the
     `## Change Requests` section. The user merges with the rest of the PRD
     when they run validation-phase.md Step 7 (`mw-docs` is invoked once per
     PRD, not per CR).

---

## Step 1 — Intake

1. If change description provided as argument: use it.
2. If not: ask the user to describe the change.

**Classify the change type** (from CIA literature):
- **Addition**: new entity (endpoint, collection, page, role, flow)
- **Modification**: change to existing entity (new field, changed behavior)
- **Deletion**: removal of planned entity

Record in state file under `## Change Requests`:

```markdown
### CR-N: <title>
- Type: Addition | Modification | Deletion
- Description: <user's description verbatim>
- Date: YYYY-MM-DD
- Status: analyzing
```

**Immediately proceed to Step 2.**

---

## Step 2 — Impact Analysis (ICIAS Protocol)

**Read [../prd/references/impact-analysis.md](../prd/references/impact-analysis.md) for the full protocol.**

Quick summary — 3 phases executed in sequence:

### Phase 1: Semantic Scan
Evaluate each of the 10 dimensions against the change request.
For each dimension, assign an initial impact assessment (0=none, 1-3=depth).

### Phase 2: Structural Propagation
Apply the coupling matrix to find transitive impacts.
Max 2 hops, confidence degrades per hop.

### Phase 3: ICIAS Scoring
For each impacted dimension: `Score = I x C x A`
- I = Impact depth (1=cosmetic, 2=logic, 3=structural)
- C = Confidence (1=inferred, 2=probable, 3=certain)
- A = Artifact Stakes (pre-assigned per dimension)

Classify: **SKIP** (score <= 3), **PATCH** (4-9), **REDO** (>= 10)

---

## Step 3 — Verdict

Present the impact matrix to the user:

```
### Impact Analysis — CR-N: <title>

| # | Dimension | Direct | Cascade | I | C | A | Score | Verdict |
|---|-----------|--------|---------|---|---|---|-------|---------|
| D1 | Target users | - | - | 0 | - | 1 | 0 | SKIP |
| D2 | User journey | yes | - | 2 | 3 | 2 | 12 | REDO |
| D3 | Data model | - | D4->D3 | 1 | 2 | 3 | 6 | PATCH |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

**Phases to re-execute:**
- Discovery: PATCH (D2, D4 to update)
- UI Design: REDO (new flow)
- PRD: PATCH (sections 4, 6, 9)
- Backlog Cards: PATCH (new cards + update existing)

Proceed with this analysis?
```

**STOP.** Wait for user confirmation.

If user disagrees with any verdict: re-score the contested dimension at their
direction (record the override and the reason in the state file under CR-N),
then re-present the full matrix. **Maximum 2 re-presentations per CR**; after
the second re-presentation the agent must accept the user's overrides as final
and proceed. Any SKIP override from PATCH/REDO that removes a mandatory gate
(D3 schema section, API gate) is recorded as `USER_OVERRIDE` in the state file
for audit but does not block execution.

---

## Step 4 — Selective Execution

Execute ONLY phases with PATCH or REDO verdict, in original phase order.

### For Discovery dimensions (PATCH/REDO)

- **PATCH**: Run `codebase-architect` on affected dimensions only.
  Update state file checklist entries. No user questions unless ambiguous.
- **REDO**: Full re-discovery for that dimension (same as /prd Step 2 loop
  but scoped to affected dimensions only). May require user questions.

### For UI Design (PATCH/REDO)

- **PATCH**: Describe changes needed to existing design.html. Ask user
  if they want a full design refresh or text-only update to PRD.
- **REDO**: Re-run the full UI Design phase following
  [../prd/references/ui-design-phase.md](../prd/references/ui-design-phase.md)
  (Steps 3.0 Precondition → 3.1 Full / Hybrid pipeline as applicable). Pass
  `WORKING_DIRECTORY=$WORKING_DIRECTORY` to `ui-design` per the side-effect
  rules in Step 0 of this skill.

### For PRD (PATCH/REDO)

- **PATCH**: Edit specific PRD sections. Add/modify user stories, API
  contracts, data model, acceptance criteria as needed. Preserve
  unchanged sections verbatim.
- **REDO**: Rewrite major PRD sections (rare — only when change
  fundamentally alters the feature).

### For Backlog Cards (PATCH/REDO)

- **PATCH**: Create new cards for new work. Update `depends_on` in
  existing cards if dependencies changed. Do NOT rewrite existing cards
  unless acceptance criteria changed.
- **REDO**: Regenerate affected cards via `prd-card-writer` agent.
  Preserve cards that are unaffected.

  **BLOCKING pre-check before invoking `prd-card-writer`:** If the PRD
  dimension also has a PATCH or REDO verdict (step 4c), confirm that 4c is
  complete AND that the PRD document contains an up-to-date
  `## Schema Verification` section (field registry with `ts_verified: true`)
  before starting card generation. `prd-card-writer`'s Field Grounding Rule
  mandates this section exists and is current — invoking the agent before 4c
  finishes will cause it to halt after writing partial cards. Do not proceed
  if the section is absent or stale.

### For ISA (always re-scan if any PATCH/REDO exists)

Run a delta ISA scan focused on the new requirement. Merge new
touchpoints into existing ISA table. Assign new ISA-N IDs.

---

## Step 5 — Delta Commit

1. Update state file:
   - CR status: `applied`
   - Update comprehension checklist with changes
   - Update `## Change Requests` with summary of what was done
2. **Re-run API Performance Gate** if the CR produces a PATCH or REDO verdict on
   D3 (Data model) or D4 (API contracts). Read
   [../prd/references/api-perf-gate.md](../prd/references/api-perf-gate.md) for
   the full gate protocol. Invoke `api-perf-cost-auditor` following the same
   pattern as `/prd` Step 4.5. Record the gate result in the state file
   `## Change Requests › CR-N` section before the delta commit.
3. Stage ONLY modified files (explicit names).
4. Commit: `[PRD-ADD] <slug>: <CR description>`

---

## CR PROGRESS BAR — MANDATORY ON EVERY MESSAGE

```
---
🔄 **Change Request: <slug> — CR-N**

| # | Phase | Verdict | Status |
|---|-------|---------|--------|
| 1 | Intake | - | ⬜/✅ |
| 2 | Impact Analysis | - | ⬜/🔄/✅ |
| 3 | Verdict & confirm | - | ⬜/🔄/✅ |
| 4a | Discovery (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
| 4b | UI Design (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
| 4c | PRD (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
| 4d | Backlog Cards (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
| 5 | Delta Commit | - | ⬜/✅ |

Next: <what happens next>
```
