| name | sprint-manifest |
| description | Step 3 of the NONoise architectural workflow. Promotes `validated` PRDs from `docs/prd/<area>/` to `docs/sprints/Sprint-N/<area>/` and produces one aggregated Sprint Manifest at `docs/sprints/Sprint-N/sprint-manifest.md` listing all promoted PRDs, derived user stories, macro functional tasks (vertical slices) with confidence CL1/CL2/CL3, CL1 tasks flagged for decision records, and cross-area dependencies. Also handles impact analysis when a new PRD is added to an already-open sprint. USE when the user wants to promote validated PRDs to a sprint, talks about "sprint manifest", "sprint plan", "promotion to sprint", "task breakdown macro", "impact analysis on sprint", or "update sprint with new PRD". Triggers — `sprint-manifest area <area> sprint <N>`, `sprint-manifest sprint <N>`, `sprint-manifest sprint <N> update`. Also triggers without explicit mention on "promote <area> to sprint <N>" or "create sprint <N> plan". |
| source | Risko reference-project (reworked whitelabel for NONoise) |
| variant | nonoise generic; stack-neutral; one aggregated manifest per sprint |
Before running this skill's procedure: ask the user to describe the full scope in one message (who, what, why, constraints, success criteria). Treat the rest of this document as a schema to fill against their answer, not a turn-by-turn questionnaire. Only ask follow-up questions for genuine blockers.
sprint-manifest — Sprint Manifest + PRD promotion
This skill is step 3 of the NONoise architectural workflow. It takes validated PRDs (output of arch-decision) and promotes them into a specific sprint, producing one aggregated Sprint Manifest per sprint that coordinates execution and defines the macro functional tasks developers will implement.
Position in the workflow
┌─────────────┐ ┌──────────────┐ ┌──────────────────┐
│ arch- │──▶│ arch- │──▶│ sprint-manifest │
│ brainstorm │ │ decision │ │ (THIS SKILL) │
│ │ │ │ │ │
│ produces │ │ validates │ │ promotes PRDs │
│ PRDs as │ │ via │ │ to sprint + │
│ draft │ │ quint-fpf │ │ aggregated │
│ │ │ │ │ manifest │
└─────────────┘ └──────────────┘ └──────────────────┘
STEP 1 STEP 2 STEP 3
What this skill does
- Promotes
validated PRDs by moving them from docs/prd/<area>/ to docs/sprints/Sprint-N/<area>/.
- Generates (or updates) one aggregated Sprint Manifest at
docs/sprints/Sprint-N/sprint-manifest.md — a single sprint-level document listing all PRDs, deriving user stories, breaking work into macro tasks, mapping dependencies.
- Runs impact analysis when a new PRD is added to an already-open sprint with an existing manifest.
- Assigns confidence CL1 / CL2 / CL3 to tasks and flags CL1 tasks that require a dedicated decision record before implementation.
- Provides the seed for downstream work-item export skills (e.g.
spec-to-workitem, devops-push if installed).
What this skill does NOT do
- Does not create PRDs — that is
arch-brainstorm's job. If the user wants a new PRD, redirect.
- Does not validate PRDs — if a PRD is not
validated, stop and redirect to arch-decision.
- Does not write to
docs/architecture/ — the architect updates the source of truth manually (driven by arch-decision Phase 6 "Impact on docs/architecture/" checklist), independently from this skill.
- Does not generate per-feature micro-manifests — one aggregated manifest per sprint, never split by area or by PRD.
- Does not produce technical breakdowns — tasks are vertical functional slices, not lists of files/classes/migrations to create.
- Does not push to external issue trackers — that is a separate skill invoked explicitly afterwards.
Golden rule — MACRO granularity (read twice)
This is the most important rule of this skill. Tasks and user stories must be VERTICAL FUNCTIONAL SLICES, not horizontal technical layers.
A developer must be able to take a task, implement it end-to-end, test it in a visibly-functional way, and deliver it as a unit of value. Decomposition into files, classes, migrations, unit tests is implementation detail and is the developer's responsibility — it must not be in the manifest.
Concrete example — hypothetical study user-signup/01-email-otp
❌ WRONG — technical-layer tasks
- Task 1: Create migration for table `SignupSessions`
- Task 2: Create `SignupSession` entity in auth-service
- Task 3: Create ORM mapping for the new entity
- Task 4: Create `IEmailProvider` interface
- Task 5: Create `SendgridEmailProvider` implementation
- Task 6: Create `IOtpPolicy` interface
- Task 7: Create `DefaultOtpPolicy` implementation
- Task 8: Create `StartSignupHandler` skeleton
- Task 9: Create `SignupController` with POST /signup/start
- Task 10: Create `VerifyOtpCommand` in auth-service
- Task 11: Create `VerifyOtpHandler` in auth-service
- Task 12: Create endpoint POST /signup/verify-otp
- Task 13: Create `SignupNotificationHandler` in notifications
- ... (continues for another 10 tasks)
Why this is wrong:
- No task delivers visible functional value. Task 1 alone does nothing testable.
- The dev can't deliver incrementally — must do everything before seeing a result.
- The breakdown assumes the full technical architecture (classes, files). The manifest is deciding it, not the dev.
- Separate-layer tasks (DB, handler, controller) → forces rigid ordering and blocks parallel work at the functional level.
✅ RIGHT — functional-slice tasks
- Task 1: "Operator starts signup with email and receives an OTP"
POST /signup/start accepts an email, creates a session, emits an OTP via email provider.
Visible test: curl POST → 200 + email received in Mailhog with 6-digit OTP.
Confidence: CL2 (email pattern already in use for password-reset)
Effort: 3–5 days
- Task 2: "Operator verifies OTP and receives a session token"
POST /signup/verify-otp validates the OTP, marks the session complete, returns a JWT.
Visible test: end-to-end — start signup, read OTP, submit it, get token, token validates on protected endpoint.
Confidence: CL2 (JWT issuance pattern already in production)
Effort: 2–3 days
- Task 3: "Expired OTP blocks verification with clear error"
Sessions older than 10 minutes reject verification with a 410 Gone and a human message.
Visible test: wait 11 minutes, submit OTP, receive 410 with error code `OTP_EXPIRED`.
Confidence: CL3 (straightforward TTL check)
Effort: 1 day
- Task 4: "Operator receives email with branded template and correct locale"
Email template derives from locale header, uses shared branding, OTP is bold 6 chars.
Visible test: send signup with `Accept-Language: it` → email body is in Italian.
Confidence: CL1 (new template system, no prior) → [DECISION RECORD NEEDED on template resolution]
Effort: 2–4 days
Why this is right:
- Each task delivers visible, testable functional value.
- The dev can work on them in parallel (with clear inter-task deps where they exist).
- The dev decides how to structure classes, files, migrations autonomously. The task says "what it does", not "how".
- Confidence CL is on the functional task, not on a single file — more meaningful.
- The developer can demo at the end of each task.
Practical rule
| Question | If NO → the task is too micro |
|---|
| Does the task deliver a visible feature or end-to-end-testable behavior? | Too micro |
| Could a developer demo the result of this task alone? | Too micro |
| Would the task survive a refactor of internal file/class structure? | Too micro (too tied to code shape) |
| Does the task name sound like "implement feature X" or "enable Y"? | OK, macro |
If the task name is "Create class X.ts" or "Add column Y to table Z", it's wrong. If it's "Let the operator do Q" or "Enable flow R", it's right.
Typical task size
| Measure | Typical value |
|---|
| Effort | 2–5 days of dev (includes tests) |
| Files touched | Typically 5–15 files across 2–4 layers |
| Components involved | Typically 1–3 |
| Demo-ability | Yes — result shown in ~5 minutes |
If a task is estimated >8–10 days, it is probably too big and should be split into 2 separate functional tasks. If a task is estimated <1 day, it is probably a hidden technical refactor and should be absorbed into a neighboring macro task.
User stories sit above tasks
User stories are even higher than tasks — they are complete user experiences. Example for area user-signup:
- US1 — Self-serve signup: "As a new visitor, entering my email I receive an OTP and, after verifying it, I have an authenticated session."
- US2 — Clear error recovery: "As a new visitor with an expired OTP, I see a clear error and can request a new one without losing my progress."
A user story is delivered by multiple tasks (typically 3–8 per US). Tasks are the internal units of work; the user story is the externally-visible outcome.
Arguments
$ARGUMENTS can be:
sprint N — sprint N, process all validated PRDs from all areassprint N area=<slug> — sprint N, process only the specified areasprint N area=<slug> prd=NN — sprint N, promote only one specific PRD of the areasprint N update — sprint N, update the existing manifest with a new PRD (impact analysis)sprint N regenerate — rebuild the manifest from scratch reading all already-promoted PRDs
If arguments are missing, ask the user for sprint + source.
Flow — 5 steps
Step 0 — determine the mode
Inspect arguments and repo state:
| Mode | Trigger | What it does |
|---|
| A. First manifest | Sprint-N/sprint-manifest.md does not exist, validated PRDs ready | Promote PRDs, create manifest from scratch |
| B. Impact analysis | Sprint-N/sprint-manifest.md exists, a new PRD arrives | Promote the new PRD, update the existing manifest with impact analysis |
| C. Regenerate | User wants to rebuild the manifest without changing PRDs | Re-read promoted PRDs and rebuild the manifest |
Always announce the detected mode to the user.
Step 1 — check prerequisites
Before touching any file:
-
Check PRD state: every PRD to process must have status: validated in its frontmatter.
draft → redirect: "PRD X is still in draft. Run arch-decision <path> before promoting it."superseded → skip with a log entry (not an error)rejected → skip with a log entrypromoted → already in a sprint, skip- Unrecognized frontmatter → error, ask the user what to do
-
Check target sprint: if the user has not specified the sprint, ask explicitly via AskUserQuestion. The sprint is mandatory.
-
Check area consistency: the area slug in the PRD frontmatter must match the folder name under docs/prd/. If there is a mismatch, flag it.
-
Check audit folder: for every validated PRD there should be a matching audit folder at docs/prd/<area>/audit/NN-<study>-fpf/ containing 05-decision.md (the DRR). If the folder or 05-decision.md is missing, flag as warning but continue (non-blocking).
If any check fails and is not recoverable, stop and ask the user how to proceed.
Step 2 — promote PRDs
For every validated PRD to process:
-
Move the files from draft to sprint area:
docs/prd/<area>/NN-<study>.md
→ docs/sprints/Sprint-N/<area>/NN-<study>.md
docs/prd/<area>/NN-<study>-diagrams.md
→ docs/sprints/Sprint-N/<area>/NN-<study>-diagrams.md
docs/prd/<area>/audit/NN-<study>-fpf/
→ docs/sprints/Sprint-N/<area>/audit/NN-<study>-fpf/
The audit is a folder, not a single file — move the entire folder (all 6 per-phase files) as a unit.
-
Copy 00-area-brief.md into the sprint area folder on first promotion of that area, annotated with "Promoted to Sprint N in YYYY-MM-DD".
-
Update the frontmatter of the moved PRDs:
status: promoted
sprint: <N>
promoted_at: YYYY-MM-DD
-
Leave a short pointer in docs/prd/<area>/ if the area has no remaining drafts — add a note in 00-area-brief.md (don't remove the brief): "Studies promoted to Sprint N. Reuse this slug for new studies on this area." If there are still draft or validated non-promoted studies in the area, keep them in place and update the brief index accordingly.
Step 3 — generate or update the Sprint Manifest
The sprint manifest lives at docs/sprints/Sprint-N/sprint-manifest.md. One file per sprint, not per area or per PRD.
Mode A (first manifest)
Create the file from scratch using the template below.
Mode B (impact analysis)
-
Read the existing manifest.
-
Read the newly-promoted PRDs.
-
For each task in the existing manifest, classify the impact:
| Class | Meaning | Action |
|---|
| UNCHANGED | No new PRD touches this functional area | Skip |
| UPDATE | A new PRD modifies contracts/behavior that affect this task | Update the task in the manifest (inline Edit) |
| NEW | Feature not covered by any existing task | Add a new task to the manifest |
| CONFLICT | The new PRD contradicts an existing task | Flag, ask the user |
-
Present the impact table to the user before touching any file. Explicit approval required.
-
Apply changes via Edit, never overwrite the whole file.
-
Append a changelog entry to the manifest:
## Changelog
- YYYY-MM-DD — Updated with PRD <area>/<NN-study>: [tasks X, Y added; tasks Z updated]
Mode C (regenerate)
Rebuild the manifest from scratch by reading all promoted PRDs. Use with caution — overwrites the existing manifest. Ask for explicit confirmation.
Step 4 — apply the macro-granularity principle
When generating tasks for the manifest, rigorously apply the macro principle described above:
-
Start from user stories: for every PRD, extract 1–3 user stories from the "Decision story" and "Code changes checklist" sections. User stories are complete user experiences.
-
From user stories to tasks: for every user story, identify 3–8 macro functional tasks. Every task is a testable vertical slice.
-
Do not split by layer: if you find yourself writing "Create aggregate X", "Create repository X", "Create handler X", stop and aggregate. They are all part of the same functional task ("Enable operation on X").
-
Every task has:
- Functional name (not "Create class X")
- Description (what it does when done — visible behavior)
- Visible acceptance test (how to verify, typically integration / end-to-end)
- Confidence CL1 / CL2 / CL3 (how well-known the pattern is)
- Effort (days, typically 2–5)
- Dependencies (other tasks that must be done first)
- Area (reference to the source PRD)
-
If total effort of an area exceeds the sprint, flag it to the user. Do not arbitrarily shrink.
-
Reject micro patterns: if a user who read the manifest says "I need more detail", answer that detail is the developer's responsibility during implementation and belongs in code, not in the manifest.
Step 5 — output and next steps
-
Summary to the user:
- Target sprint: N
- Promoted PRDs: list (area / NN-study)
- Manifest: path
- User stories: N
- Macro tasks: N (total effort X days)
- Tasks with confidence CL1 (decision record needed): N
- Conflicts detected (mode B): N resolved / N open
-
CL1 flag → decision record needed:
The following tasks have confidence CL1 and require an explicit decision record
before implementation:
- Task X: "<name>" → reason: <new pattern, no prior>
- Task Y: "<name>" → reason: <new tech never used in the project>
Want me to open an arch-brainstorm study for one of these?
-
Suggested next step:
✅ Sprint <N> ready with manifest.
Next recommended steps:
- Human review of the manifest: <path>
- For CL1 tasks: run `arch-brainstorm` on the topic to close the knowledge gap
- For external work-item export: if a skill like `spec-to-workitem` or `devops-push` is
installed, invoke it on the manifest; otherwise copy tasks manually to your tracker
- To add more PRDs to this sprint: `arch-brainstorm` + `arch-decision` + `sprint-manifest sprint <N> update`
-
Never push automatically to external trackers. That is an action with external side effects — it must be explicit and invoked separately.
Sprint Manifest template
Mandatory structure for docs/sprints/Sprint-N/sprint-manifest.md:
---
title: "Sprint <N> — Manifest"
sprint: <N>
kind: sprint-manifest
status: draft | approved | completed
created_at: YYYY-MM-DD
updated_at: YYYY-MM-DD
areas_covered: [<area-1>, <area-2>]
prd_refs:
- area: <area-1>
studies: [01-<study>, 02-<study>]
- area: <area-2>
studies: [01-<study>]
total_effort_days: <number>
---
# Sprint <N> — Manifest
> Sprint-level aggregator of the validated PRDs promoted to this sprint.
> Contains the breakdown in user stories and macro functional tasks for implementation.
## 1. Sprint goal
<1–2 sentences summarizing the sprint objective, derived from the goals of the promoted
PRDs. Example: "Enable self-serve signup with email + OTP verification, with clear error
recovery paths and audit trail of all attempts.">
## 2. PRDs included in this sprint
| Area | Study | Path | Goal | Aggregate confidence |
|---|---|---|---|---|
| user-signup | 01-email-otp | [path](./user-signup/01-email-otp.md) | OTP-based signup flow | CL2 |
| ... | ... | ... | ... | ... |
## 3. User stories
### US1 — <user-experience name>
**As** <role>, **I want** <what>, **so that** <why>.
**Covered by PRD**: <area>/<study>
**Acceptance test**: <how to verify end-to-end>
**Confidence**: CL2
### US2 — ...
## 4. Macro functional tasks
### Task T1 — <functional name>
- **Area**: <area-slug>
- **User story**: US1
- **Description**: <visible behavior when the task is done. 2–3 sentences, not a file list.>
- **Acceptance test**: <how to verify. Typically integration / end-to-end.>
- **Confidence**: CL1 | CL2 | CL3
- **Estimated effort**: <X> days
- **Dependencies**: [T2, T5] (or "none")
- **Components touched**: [auth-service, notifications]
- **Relevant PRD sections**: §2.2 "Flow", §5 "Target architecture"
### Task T2 — ...
## 5. Dependencies and execution order
```mermaid
graph LR
T2[T2: notifications email template] --> T1[T1: signup start + OTP]
T1 --> T3[T3: OTP verify + token]
T1 --> T4[T4: expired OTP error]
T5[T5: locale resolution] --> T2
6. Tasks with CL1 confidence (decision record needed)
Every CL1 task requires a dedicated decision record before implementation:
| Task | CL1 reason | Proposed DR / new arch-brainstorm study |
|---|
| T5 | Locale resolution policy new, no prior pattern | DR-NNN: "Locale resolution for templated emails" |
7. Risks and mitigations
| Risk | Severity | Mitigation |
|---|
| 🔴/🟠/🟡 | |
8. Out of scope for this sprint
Explicit list of things NOT being done this sprint (even if they appear in PRDs):
9. Next steps after manifest
Changelog
- YYYY-MM-DD — Manifest created by sprint-manifest (first run)
- YYYY-MM-DD — Updated with PRD / (impact analysis)
---
## Operating principles
1. **One manifest per sprint** — never separate files by area or by PRD. The manifest is the only sprint-level artifact.
2. **PRDs are immutable after promotion** — once promoted, the PRD in the sprint folder is frozen. If an important change is needed, create a new study (`02-<study>`) in `docs/prd/<area>/` and promote it with impact analysis.
3. **Macro granularity is mandatory** — reject any attempt at technical-layer tasks. If the user asks for more detail, explain that it is the developer's responsibility.
4. **CL1 → explicit decision record** — every CL1 task generates an entry in section 6 of the manifest. Do not swallow the risk.
5. **Impact analysis with approval** — never touch an existing manifest without presenting the impact table and getting approval.
6. **No automatic external push** — the manifest is a planning document. Export to a tracker is a separate, explicit action.
---
## Anti-patterns
1. **Technical-layer tasks** — "Create class X", "Create migration Y", "Add field Z". Always wrong. See the macro-granularity principle.
2. **Manifest too granular** — 50+ tasks per sprint is a signal that you are over-splitting. Aim at 10–20 macro tasks.
3. **Manifest too vague** — tasks without a visible acceptance test are not implementable.
4. **Over-generous confidence** — do not rate everything CL3. Be honest: if you have not seen the pattern in the codebase, it is CL2 at most. If the technology is new, it is CL1 and needs a decision record.
5. **Ignoring conflicts** — if a new PRD conflicts with an existing task, you MUST stop and ask the user. Never resolve silently.
6. **Unchanged PRD after impact analysis** — if a new PRD causes UPDATE on another PRD's tasks, that is a signal the two PRDs should be reviewed together. Flag it.
## When NOT to use this skill
- No PRD is in `validated` state → use `arch-brainstorm` + `arch-decision` first
- The user wants to push work items directly → use a dedicated export skill
- The user wants to change a PRD already promoted → create a new study, do not edit the promoted one
---
## Reference files
- `docs/prd/<area>/*.md` — source of validated PRDs
- `docs/sprints/Sprint-N/` — promotion destination (one folder per sprint)
- `docs/sprints/Sprint-N/sprint-manifest.md` — the aggregated sprint manifest (one per sprint)
- `docs/sprints/Sprint-N/<area>/*.md` — promoted PRDs + audits
- `docs/architecture/` — source of truth (read-only for this skill)
## Related skills
- [`arch-brainstorm`](../arch-brainstorm/SKILL.md) — produces PRDs (step 1)
- [`arch-decision`](../arch-decision/SKILL.md) — validates PRDs via `quint-fpf` (step 2)
- Future `spec-to-workitem` / `devops-push` — translate the manifest into external work items (next step after this skill, optional)
