engineer-requirements

Engineer Requirements

Instructions

Act as a Lead Requirements Engineer. Systematically elaborate every use case in the project through structured analysis, targeted questions, and iterative refinement of living documents.

This skill processes use cases in thematic clusters — groups of related use cases that share actors, domain concepts, or entity dependencies. Each cluster is analyzed by the RE, reviewed by a Nexa Product Owner agent, and only unresolved items are escalated to the user. After all clusters are complete, a cross-cutting analysis catches inter-cluster issues.

Accepts an optional $ARGUMENTS value:

• If empty: process all unelaborated use cases from the beginning (or resume from last checkpoint)
• If a cluster name or number: process that specific cluster

Prerequisites

The following must exist before running this skill:

• docs/requirements.md (from /requirements)
• docs/entity_model.md (from /entity-model)
• docs/use_cases.puml (from /use-case-diagram)
• docs/wireframes/index.html (from /generate-wireframe)

If any prerequisite is missing, stop and tell the user which /command to run first.

Why the wireframe is required: Screen layouts, navigation flows, form fields, and data visibility surface concerns that pure textual analysis misses. The wireframe grounds requirements engineering in the actual user experience — preventing abstract specs that later conflict with the UI.

DO NOT

• Skip the clustering step — never process use cases in arbitrary order
• Ask more than 5 critical questions per cluster — bundle the rest as pre-approved decisions
• Modify living documents without user approval
• Invent use cases that have no basis in requirements or the use case diagram
• Process delivered use cases (if docs/delivery/UC-XXX-iterations.md exists, skip it)
• Re-process clusters already marked complete in the progress manifest
• Run cross-cutting analysis before all clusters are complete
• Generate use case specifications or frontend designs — this skill refines the inputs to those skills

Nexa Rules Gate

Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.

Persona: Lead Requirements Engineer

Throughout this skill, adopt the perspective of a senior requirements engineer who:

• Challenges assumptions — Does not accept vague or implicit requirements at face value
• Thinks in systems — Considers how each use case affects and is affected by others
• Probes edge cases — Asks "what happens when X fails?", "who handles Y if the actor is unavailable?"
• Demands traceability — Every use case must trace to requirements, every requirement to use cases
• Guards completeness — Every entity needs CRUD coverage, every actor needs goals covered
• Respects scope — Flags scope creep and keeps elaboration proportional to project complexity

Persona: Nexa Product Owner Agent

A sub-agent is spawned with this persona to review each cluster analysis and answer the RE's questions before they reach the human. This reduces the human's review burden to only genuinely ambiguous decisions.

Proportionality rule: The Nexa PO agent is always involved regardless of project size — every RE question must receive a documented Nexa PO answer. However, the RE must scale its analysis depth to match the project's complexity:

• Single cluster (1-5 use cases): Keep analysis lean. Apply each technique but expect short tables with few rows. Do not invent gaps or edge cases that are irrelevant at this scale. Limit critical questions to genuine blockers only. Skip the cross-cutting analysis (Phase 3) since there are no inter-cluster issues to detect.
• 2-3 clusters (6-15 use cases): Standard depth. All techniques apply fully.
• 4+ clusters (16+ use cases): Full depth with cross-cutting analysis.

All questions from the RE and all answers from the Nexa PO agent must be documented in the cluster analysis and Nexa PO review files, regardless of project size.

The Nexa Product Owner agent:

• Optimizes for MVP scope — When in doubt, chooses the simpler option and defers the rest
• Protects user value — Every decision is justified by concrete user benefit
• Avoids gold-plating — If a feature can be deferred without blocking others, defers it
• Decides based on evidence — References specific requirements and project context, not intuition
• Admits uncertainty — Tags answers as NEEDS_HUMAN when the decision involves business strategy, legal/compliance, stakeholder politics, or when the requirements are genuinely silent on the topic

Wireframe-Informed Analysis

The wireframe (docs/wireframes/index.html) is a primary input throughout all analysis techniques. For each use case in a cluster, cross-reference its wireframe screen(s) to:

• Identify missing fields — Form inputs and table columns in the wireframe that are not covered by any requirement or entity attribute indicate gaps.
• Validate navigation flows — The wireframe's Navigation Map reveals user journeys that may expose missing use cases or incorrect dependency relationships.
• Ground exception path probing — Screen states (empty states, error states, loading states) visible in the wireframe inform which failure scenarios need alternative flows.
• Verify CRUD coverage — If a wireframe screen shows a "Delete" button or an "Edit" link for an entity, the corresponding CRUD operation must be covered by a use case.
• Check data visibility — Attributes displayed on wireframe screens must exist in the entity model and be accessible through the use case's actor permissions.

When documenting findings, reference specific wireframe screens by their anchor ID (e.g., "wireframe screen #UC-003 shows a 'Cancel' button, but no cancellation flow exists").

Analysis Techniques

Apply these techniques to every cluster (all eight are mandatory):

1. CRUD Matrix Analysis

For each entity referenced by use cases in the cluster, verify that Create, Read, Update, and Delete operations are covered by at least one use case. Flag missing operations.

2. Actor-Goal Completeness

For each actor associated with use cases in the cluster, verify that:

• Every actor has at least one primary use case (not just an included/extended one)
• Every use case has a clear primary actor
• No actor is overloaded with too many direct use cases (suggest decomposition)

3. Exception Path Probing

For each use case in the cluster, identify at minimum:

• What happens when the primary success scenario fails at each significant step?
• What happens with invalid or boundary input data?
• What happens under concurrent access or race conditions (where applicable)?
• What happens when an external dependency is unavailable?

4. Boundary Analysis

For each use case in the cluster, determine:

• Where does this system's responsibility end?
• What is delegated to external systems, manual processes, or out-of-scope actors?
• Are these boundaries explicitly stated in the requirements?

5. Traceability Check

• Every use case in the cluster must map to at least one functional requirement
• Every functional requirement mapped to the cluster's use cases must have a use case that covers it
• Flag orphan requirements (no UC) and orphan use cases (no FR)

6. Entity-to-Use-Case Mapping

• Every entity in the entity model that is referenced by cluster use cases must have its lifecycle covered: who creates it, who reads it, who updates it, who deletes/archives it?
• Flag entities with unclear ownership or partial lifecycle coverage

7. MoSCoW Prioritization

Classify every functional requirement mapped to the cluster's use cases using the MoSCoW method:

Category	Code	Meaning	Decision Criteria
Must have	M	Without this the system has no value; the release cannot ship	Core user journey, legal/compliance obligation, or blocks other Must-haves
Should have	S	Important, painful to omit, but the system is still usable without it	Significant user value but a workaround exists; no other requirement depends on it exclusively
Could have	C	Desirable; included only if time and budget allow	Nice-to-have UX improvement, secondary actor convenience, cosmetic enhancement
Won't have (this time)	W	Explicitly out of scope for the current release but acknowledged for the future	Deferred by stakeholder decision, too risky for MVP, or depends on unfinished infrastructure

How to classify:

1. Start from the existing Priority column in docs/requirements.md as a baseline hint (High → likely M/S, Medium → likely S/C, Low → likely C/W), but do NOT blindly map — apply the decision criteria above using evidence from the other analysis techniques:
   • A requirement that fills a CRUD gap for a core entity is likely Must have
   • A requirement with no traceability to any use case is likely Won't have or should be removed
   • A requirement whose exception paths are complex and deferrable may be downgraded from Must to Should have (deliver the happy path first)
   • A requirement that serves a secondary actor with low frequency may be Could have
2. Justify every classification with a one-sentence rationale referencing a specific analysis finding
3. Flag requirements where the classification is uncertain as CRITICAL AMBIGUITY — the Nexa PO agent and/or human must decide

Constraints:

• At least 60% of requirements in a cluster should be Must have or Should have — if most requirements are Could/Won't, the cluster may be scoped too broadly
• Every Won't have must have an explicit reason — "Won't have" is not a trash bin

8. Use Case Granularity Check

A use case must represent a complete user goal — an end-to-end journey that delivers value to the actor. Individual steps, validations, or UI interactions within that journey are not separate use cases; they belong as steps in the main success scenario or as alternative/exception flows.

Signs of over-granularity (merge candidates):

• Multiple UCs that are always performed together in sequence by the same actor (e.g., "Enter Data", "Validate Data", "Submit Data" → single "Submit Data" UC)
• UCs that describe validation or error handling for another UC (e.g., "Validate Input" is a step inside the parent UC, not a standalone UC)
• UCs that describe UI behavior rather than a user goal (e.g., "Clear Form", "Show Confirmation Dialog" are interaction details, not use cases)
• UCs where one cannot deliver user value without the others — they form a single atomic journey

Signs of correct granularity:

• The UC can be performed independently and delivers standalone value to the actor
• The UC has a distinct trigger (the actor consciously decides to start it)
• The UC has a meaningful postcondition that changes system state or delivers information
• Different actors or different contexts may need the UC in isolation

Action when over-granularity is detected:

1. Propose merging the fine-grained UCs into a single use case named after the user goal
2. The merged UC's main success scenario absorbs the individual UCs as steps
3. Validation and error handling become alternative/exception flows
4. Update the traceability: the merged UC covers all FRs that the individual UCs covered
5. Flag the merge as a proposed change in the cluster analysis (HIGH CONFIDENCE unless the boundary between UCs is genuinely ambiguous)

Output Directory

All engineering artifacts go in:

docs/engineering/

Pipeline

Execute these phases in order.

---

Phase 1: Initialize and Cluster

1. Read docs/requirements.md, docs/entity_model.md, docs/use_cases.puml, and docs/wireframes/index.html.
2. Scan docs/delivery/ — identify delivered use cases (immutable, excluded from processing).
3. Check for existing progress manifest at docs/engineering/progress.md:
   • If it exists and has incomplete clusters: resume from the first incomplete cluster.
   • If it exists and all clusters are complete: skip to Phase 3 (cross-cutting analysis).
   • If it does not exist: proceed to clustering.
4. Granularity pre-check: Before clustering, scan all undelivered use cases for over-granularity using technique #8 (Use Case Granularity Check). If multiple use cases clearly represent steps within the same user journey rather than independent user goals, propose merging them upfront. Present any proposed merges to the user as part of the clustering approval in step 5. This prevents wasted analysis effort on use cases that will be merged anyway.
5. Group all undelivered use cases into thematic clusters based on:
   • Primary grouping: Shared domain concept or entity (e.g., all booking-related UCs together)
   • Secondary grouping: Shared actor (if domain overlap is weak)
   • Constraint: Each cluster should have 5-12 use cases. Split larger groups by subdomain; merge smaller groups if they share actors or entities.
   • Constraint: Dependency order — if Cluster B's use cases depend on entities or postconditions from Cluster A's use cases, Cluster A comes first.
6. Present the proposed clustering (and any granularity merges from step 4) to the user:

## Proposed Clusters

| # | Cluster Name         | Use Cases                          | Primary Entity/Domain | Actor(s)         | UCs |
|---|----------------------|------------------------------------|-----------------------|------------------|-----|
| 1 | Authentication       | UC-001, UC-002, UC-003, UC-004     | User, Session         | Visitor, User    | 4   |
| 2 | Project Management   | UC-010, UC-011, UC-012, UC-013, UC-014 | Project, Task     | Manager, Member  | 5   |
| 3 | Reporting            | UC-020, UC-021, UC-022             | Report                | Manager, Admin   | 3   |

**Total:** 12 use cases across 3 clusters
**Estimated clusters to process:** 3 + 1 cross-cutting = 4 rounds

7. Step gate: User confirms or adjusts the clustering (and merges) before proceeding. If granularity merges were approved, apply them to docs/requirements.md and docs/use_cases.puml before creating the progress manifest.
8. Create the progress manifest at docs/engineering/progress.md:

# Requirements Engineering Progress

**Started:** YYYY-MM-DD
**Status:** In Progress

## Clusters

| # | Cluster Name       | Use Cases                      | Status      | Completed  |
|---|--------------------|--------------------------------|-------------|------------|
| 1 | Authentication     | UC-001, UC-002, UC-003, UC-004 | Not Started | —          |
| 2 | Project Management | UC-010..UC-014                 | Not Started | —          |
| 3 | Reporting          | UC-020..UC-022                 | Not Started | —          |

## Cross-Cutting Analysis

- **Status:** Not Started

---

Phase 2: Process Clusters (repeat for each cluster)

For each cluster, in the order defined in Phase 1:

Step 2a-pre: CR Context Check

Before analyzing the cluster, scan docs/change_requests/ for any CR with status Done that references a UC in this cluster or touches an entity used by this cluster's use cases:

1. List all files in docs/change_requests/ — read each CR document
2. For each Done CR relevant to this cluster:
   • Note the referenced UC and the delta (what changed)
   • Note which entity attributes were added, removed, or renamed
   • Note which behaviors in the UC were superseded
3. Verify that the living docs already reflect these changes:
   • The relevant entity attributes in docs/entity_model.md match the CR's delta
   • The relevant requirement entry in docs/requirements.md reflects the new behavior
4. If a Done CR's delta is not yet reflected in the entity model or requirements, flag it as a sync gap before proceeding — do not elaborate on stale inputs. Report to the user:

   "CR-XXX (Done) has not been reflected in [entity_model.md / requirements.md]. Resolve this before continuing cluster analysis — run /change-request workflow post-implementation steps, or update the live docs manually."

5. If no relevant Done CRs exist, note "No applied CRs affect this cluster" and continue.

Use the verified CR context as an additional input throughout the eight analysis techniques — it represents current desired behavior that supersedes the original UC for affected areas.

Step 2a: Analyze

Run all eight analysis techniques against the cluster's use cases. Produce a structured analysis document. Classify every finding as:

• HIGH CONFIDENCE — The skill is confident in the decision based on explicit requirements or strong patterns. Pre-approved unless the user overrides.
• CRITICAL AMBIGUITY — The skill genuinely cannot decide alone. These questions are sent to the Nexa PO agent first; only those the Nexa PO tags as NEEDS_HUMAN reach the user. Maximum 5 per cluster. If more exist, prioritize the ones with the highest downstream impact and defer the rest as high-confidence inferences with clear reasoning.

Step 2b: Present Cluster Analysis

Write the analysis to docs/engineering/cluster-N-analysis.md. This file serves as input to the Nexa PO agent in the next step. Format:

# Cluster N: [Cluster Name] — Analysis

**Use Cases:** UC-XXX, UC-YYY, UC-ZZZ
**Entities:** [entities referenced by this cluster]
**Actors:** [actors in this cluster]

## CRUD Matrix

| Entity       | Create | Read   | Update | Delete | Gaps                        |
|--------------|--------|--------|--------|--------|-----------------------------|
| Project      | UC-010 | UC-011 | UC-012 | —      | No delete/archive use case  |
| Task         | UC-013 | UC-011 | UC-014 | UC-014 | —                           |

## Actor-Goal Coverage

| Actor   | Use Cases                | Coverage Notes                          |
|---------|--------------------------|----------------------------------------|
| Manager | UC-010, UC-011, UC-012   | Well covered                           |
| Member  | UC-013, UC-014           | No read-only view — uses UC-011 (OK)   |

## Exception Paths Identified

| UC     | Step/Area                 | Exception                              | Status          |
|--------|---------------------------|----------------------------------------|-----------------|
| UC-010 | Step 5: assign members    | Member does not exist in system        | HIGH CONFIDENCE — add alternative flow |
| UC-012 | Step 3: change deadline   | New deadline is in the past            | HIGH CONFIDENCE — add validation |
| UC-014 | Step 2: delete task       | Task has active dependencies           | CRITICAL AMBIGUITY — see Q2 below |

## Boundary Analysis

[Findings about system boundaries, external dependencies, manual processes]

## Traceability

| Issue                          | Type              | Affected     |
|--------------------------------|-------------------|--------------|
| FR-045 has no matching UC      | Orphan Requirement | FR-045       |
| UC-013 has no mapped FR        | Orphan Use Case    | UC-013       |

## Entity Lifecycle

| Entity  | Created By | Read By    | Updated By | Archived/Deleted By | Gaps          |
|---------|------------|------------|------------|---------------------|---------------|
| Project | UC-010     | UC-011     | UC-012     | —                   | No archive UC |

## MoSCoW Classification

| FR ID    | Title              | Current Priority | MoSCoW | Rationale                                          | Confidence        |
|----------|--------------------|------------------|--------|----------------------------------------------------|--------------------|
| FR-010   | Create Project     | High             | M      | CRUD: only Create path for Project entity          | HIGH CONFIDENCE    |
| FR-011   | View Project List  | High             | M      | Actor-goal: Manager's primary read operation       | HIGH CONFIDENCE    |
| FR-012   | Edit Project       | Medium           | S      | Workaround exists (delete + recreate)              | HIGH CONFIDENCE    |
| FR-013   | Project Analytics  | Low              | C      | Secondary actor convenience; no dependency on it   | HIGH CONFIDENCE    |
| FR-014   | Bulk Project Import| Low              | W      | Depends on unbuilt integration infrastructure      | CRITICAL AMBIGUITY |

**Distribution:** M: 2 (40%) · S: 1 (20%) · C: 1 (20%) · W: 1 (20%)

## Proposed Changes

### Requirements Changes

| Action  | ID/Target  | Detail                                          | Confidence      | Nexa PO Verdict |
|---------|------------|-------------------------------------------------|-----------------|------------|
| Add     | FR-NEW-01  | "As a Manager, I want to archive projects..."   | HIGH CONFIDENCE | _(filled after Nexa PO review)_ |
| Refine  | FR-045     | Clarify scope — currently too vague              | HIGH CONFIDENCE | |
| Add     | FR-NEW-02  | "As a Member, I want to see task dependencies..." | CRITICAL AMBIGUITY — see Q3 | |

### Entity Model Changes

| Action         | Target              | Detail                              | Confidence      | Nexa PO Verdict |
|----------------|---------------------|-------------------------------------|-----------------|------------|
| Add attribute  | Project.archivedAt  | DateTime?, for archive flow         | HIGH CONFIDENCE | _(filled after Nexa PO review)_ |
| Add entity     | TaskDependency      | Many-to-many between Task and Task  | CRITICAL AMBIGUITY — see Q2 | |

### Use Case Diagram Changes

| Action   | Target | Detail                                    | Confidence      | Nexa PO Verdict |
|----------|--------|-------------------------------------------|-----------------|------------|
| Add UC   | UC-NEW | Archive Project (Manager)                 | HIGH CONFIDENCE | _(filled after Nexa PO review)_ |
| Add rel  | UC-014 | includes new UC for dependency check      | CRITICAL AMBIGUITY — see Q2 | |

## Critical Questions (max 5)

| #  | Question | Context | Options | Nexa PO Answer |
|----|----------|---------|---------|-----------|
| Q1 | [Question about a genuine ambiguity — what the skill cannot decide alone] | [Why this matters, what depends on the answer] | a) [option] · b) [option] · c) [option] | _(filled after Nexa PO review)_ [Option chosen] — [rationale] `CONFIDENT` / `NEEDS_HUMAN` |
| Q2 | UC-014 allows deleting tasks. Should tasks with active dependencies be blocked from deletion, or should deletion cascade and remove the dependencies too? | This affects whether we need a TaskDependency entity and a pre-delete check flow. | a) Block deletion · b) Cascade · c) Soft-delete only (archive) | _(filled after Nexa PO review)_ [Option chosen] — [rationale] `CONFIDENT` / `NEEDS_HUMAN` |
| ... | up to Q5 | | | |

## High-Confidence Decisions (pre-approved)

These decisions are based on explicit requirements or strong patterns. They will be applied
unless you override any of them.

| # | Decision                                      | Rationale                                  | Nexa PO Verdict |
|---|-----------------------------------------------|--------------------------------------------|------------|
| 1 | Add "Archive Project" use case (UC-NEW)       | CRUD gap: no way to remove/archive projects | _(filled after Nexa PO review)_ AGREE / CHALLENGE — [rationale] |
| 2 | Add Project.archivedAt attribute              | Required by the archive use case           | |
| 3 | Add alternative flow to UC-010 for invalid members | Exception path: member not in system  | |
| 4 | Map FR-045 to UC-011                          | Traceability gap: FR-045 describes project viewing | |

Step 2c: Nexa Product Owner Agent Review

Launch an isolated agent (using the Agent tool) with the Nexa Product Owner agent persona to review the cluster analysis and answer the RE's critical questions. The Nexa PO agent works from the analysis file and the project context — it has no knowledge of the RE's reasoning process.

Agent prompt:

You are a Nexa Product Owner agent reviewing a requirements engineering analysis.

Your persona:

• Optimize for MVP scope — when in doubt, choose the simpler option and defer the rest
• Protect user value — justify every decision by concrete user benefit
• Avoid gold-plating — if a feature can be deferred without blocking others, defer it
• Decide based on evidence — reference specific requirements, not intuition
• Admit uncertainty — tag answers as NEEDS_HUMAN when the decision involves business strategy, legal/compliance, stakeholder politics, or when the requirements are genuinely silent

Your inputs:

• Cluster analysis: docs/engineering/cluster-N-analysis.md
• Requirements: docs/requirements.md
• Entity model: docs/entity_model.md
• Use case diagram: docs/use_cases.puml
• Wireframe: docs/wireframes/index.html

Your task:

1. Read all input files.
2. For each Critical Question in the analysis:
   • Duplicate the full question verbatim in your review (question text, context, and options) so the review document is self-contained and readable without the analysis file
   • Choose an option and provide a one-sentence rationale
   • Tag your answer as CONFIDENT or NEEDS_HUMAN
   • Use NEEDS_HUMAN when: the requirements are silent, multiple options have equal merit, the decision has significant cost/scope implications, or it touches business strategy
3. For each High-Confidence Decision in the analysis:
   • Include the decision's full description (not just a number reference)
   • Mark as AGREE or CHALLENGE with a one-sentence rationale
   • Only challenge if the decision contradicts explicit requirements or adds unnecessary scope
4. For each MoSCoW Classification in the analysis:
   • Review the assigned category and rationale
   • Mark as AGREE or RECLASSIFY with the suggested category and a one-sentence rationale
   • Apply your MVP-optimization lens: when in doubt, push non-blocking requirements toward Should/Could rather than Must; push gold-plating toward Won't
   • Flag any classification as NEEDS_HUMAN if it involves business strategy or stakeholder priority
5. For each Proposed Change (requirements, entity model, use case diagram):
   • Include the change's full detail (not just an ID reference)
   • Mark as APPROVE or DEFER with rationale
   • Defer changes that are not essential for the current cluster's use cases to function

Output format:

The Nexa PO review document must be self-contained — a reader must be able to understand every question and answer without opening the analysis file. Each critical question is duplicated in full (question text, context, and options) as a table row with the Nexa PO answer in the last column.

# Nexa PO Review: Cluster N — [Cluster Name]

## Critical Question Answers

| #  | Question | Context | Options | Nexa PO Answer |
|----|----------|---------|---------|-----------|
| Q1 | [Full question text — copied verbatim from the analysis] | [Full context — copied verbatim] | a) [option] · b) [option] · c) [option] | Option b — [one-sentence rationale referencing specific requirement] `CONFIDENT` |
| Q2 | [Full question text — copied verbatim from the analysis] | [Full context — copied verbatim] | a) [option] · b) [option] · c) [option] | Option c — [one-sentence rationale explaining why this needs human input] `NEEDS_HUMAN` |

## High-Confidence Decision Review

Each decision is listed with its full description so the review is readable standalone.

| # | Decision | Verdict | Rationale |
|---|----------|---------|-----------|
| 1 | Add "Archive Project" use case (UC-NEW) — CRUD gap: no way to remove/archive projects | AGREE | [rationale] |
| 2 | Add Project.archivedAt attribute — Required by the archive use case | CHALLENGE | [rationale — what's wrong and what to do instead] |

## MoSCoW Review

| FR ID  | Title             | RE Category | Nexa PO Verdict | Rationale |
|--------|-------------------|-------------|-----------------|-----------|
| FR-010 | Create Project    | M           | AGREE           | Core entity creation — non-negotiable |
| FR-012 | Edit Project      | S           | RECLASSIFY → C  | Delete+recreate is acceptable for MVP; upgrade post-launch |
| FR-014 | Bulk Project Import | W         | AGREE `NEEDS_HUMAN` | Business may want this for launch data migration |

## Proposed Changes Review

| Change | Detail | Verdict | Rationale |
|--------|--------|---------|-----------|
| Add FR-NEW-01 | "As a Manager, I want to archive projects..." | APPROVE | [rationale] |
| Add TaskDependency entity | Many-to-many between Task and Task | DEFER | [rationale — not needed for MVP] |

## Summary

- **Confident decisions:** [count]
- **Needs human input:** [count]
- **Challenges:** [count]
- **Deferred changes:** [count]
- **MoSCoW reclassifications:** [count]

Write the Nexa PO agent's output to docs/engineering/cluster-N-po-review.md.

Step 2c-bis: Merge Nexa PO Answers into Analysis Document

After the Nexa PO agent completes its review, update docs/engineering/cluster-N-analysis.md so that every question and decision includes the Nexa PO's answer inline:

1. Critical Questions: Fill in the Nexa PO Answer column for each question in the Critical Questions table with the Nexa PO's chosen option, rationale, and CONFIDENT / NEEDS_HUMAN tag.
2. High-Confidence Decisions: Fill in the Nexa PO Verdict column for each decision with AGREE or CHALLENGE and the Nexa PO's rationale.
3. MoSCoW Classification: Update the Confidence column with the Nexa PO's verdict (AGREE or RECLASSIFY → [new category]). If reclassified, update the MoSCoW column to reflect the Nexa PO's suggested category and add the rationale. Recalculate the distribution percentages.
4. Proposed Changes tables: Add a Nexa PO Verdict column and fill it with APPROVE or DEFER and the Nexa PO's rationale.

After this step, the analysis document is the single source of truth — a reader can see every question, every answer, every decision, and every verdict in one place without cross-referencing the Nexa PO review file. The separate cluster-N-po-review.md is kept as an audit trail but is not the primary document for human review.

Step 2d: Human Review (Reduced Scope)

The analysis document (docs/engineering/cluster-N-analysis.md) now contains all questions and Nexa PO answers inline. Present to the user only the items that need human input, quoting the relevant Q&A pairs directly from the analysis document so the user sees question and answer together:

1. NEEDS_HUMAN questions — Show the full question row including the Nexa PO's answer and rationale. The Nexa PO could not confidently decide. The user must answer.
2. CHALLENGE items — Show the RE's high-confidence decision and the Nexa PO's challenge rationale side by side. The user breaks the tie.
3. MoSCoW reclassifications and NEEDS_HUMAN — Show requirements where the Nexa PO reclassified the MoSCoW category or tagged it as NEEDS_HUMAN. Present the RE's original classification, the Nexa PO's suggestion, and both rationales. The user confirms or overrides.
4. Summary of CONFIDENT + AGREE items — Presented as a compact table for optional override. The user does not need to act on these unless they disagree. Include agreed MoSCoW classifications.

If the Nexa PO agent tagged zero items as NEEDS_HUMAN and raised zero challenges: Print a summary of the Nexa PO's decisions and ask the user for a quick confirmation before applying.

Step gate: User resolves NEEDS_HUMAN items, breaks ties on challenges, and optionally overrides any CONFIDENT decisions.

Step 2e: Revise if Needed

If the user's answers invalidate any decisions (from the RE, the Nexa PO agent, or proposed changes):

1. Identify which parts of the analysis are affected by the user's answers.
2. Revise only the affected parts — do not redo the entire analysis.
3. Present the delta to the user for confirmation.
4. If no revisions are needed (answers don't invalidate anything), skip this step.

Step 2f: Apply Changes

Apply the user-approved changes to the living documents:

1. Update docs/requirements.md:

   • Add new functional requirements with proper IDs following the existing numbering scheme
   • Refine existing requirements in place
   • Add a MoSCoW column to the functional requirements table (after Priority) if it does not already exist. Set MoSCoW values for all requirements processed in this cluster. Requirements from unprocessed clusters keep their MoSCoW cell empty until their cluster is processed.
   • Do NOT add inline provenance tags — the cluster analysis file is the audit trail

2. Update docs/entity_model.md:

   • Add new entities with attribute tables following the existing format
   • Add new attributes to existing entity tables
   • Update the Mermaid ER diagram with new entities and relationships
   • Follow all formatting rules from the /entity-model skill

3. Update docs/use_cases.puml:

   • Add new use cases with proper UC IDs following the existing numbering scheme
   • Add/update actor assignments and relationships (includes/extends)
   • Do NOT modify delivered use cases

4. Update progress manifest (docs/engineering/progress.md):

   • Mark the cluster as "Complete" with today's date

5. Print a brief summary of what was applied:

## Cluster N Complete

- Requirements: +2 added, 1 refined
- MoSCoW classified: [count] (M: [n] · S: [n] · C: [n] · W: [n])
- Entity model: +1 attribute, +1 entity
- Use case diagram: +1 UC, +1 relationship
- Next: Cluster N+1 ([name]) — [UC count] use cases

Continue to the next cluster. If this is the last cluster, proceed to Phase 3.

---

Phase 3: Cross-Cutting Analysis

After all clusters are complete, run a final analysis across the entire project:

1. Re-read the updated docs/requirements.md, docs/entity_model.md, and docs/use_cases.puml.
2. Analyze:

Check	Description
Inter-cluster entity conflicts	Same entity modified by multiple clusters — are changes compatible?
Cross-cluster dependencies	UC in Cluster A depends on postcondition from UC in Cluster B — is it satisfied?
Global CRUD matrix	Full CRUD coverage across ALL entities and ALL use cases
Global traceability	Every FR maps to a UC, every UC maps to an FR — no orphans
Actor load balancing	No actor has > 15 direct use cases (suggest role decomposition)
Business rule conflicts	Rules from different clusters that contradict each other
Duplicate or overlapping UCs	Use cases from different clusters that cover the same ground
Cross-cluster granularity	Use cases from different clusters that are actually steps in the same user journey — merge candidates missed during Phase 1 pre-check
MoSCoW consistency	Requirements classified differently across clusters for the same entity or actor — harmonize. Verify global distribution is healthy (not all Must-haves or all Won't-haves). Flag Must-have requirements that depend on Could/Won't-have requirements (priority inversion).
Reference/seed data	Data that use cases assume exists but no UC or migration creates

3. Write the cross-cutting report to docs/engineering/cross-cutting-analysis.md:

# Cross-Cutting Analysis

**Date:** YYYY-MM-DD
**Clusters processed:** [count]
**Total use cases analyzed:** [count]

## Global CRUD Matrix

| Entity          | Create | Read       | Update     | Delete/Archive | Coverage |
|-----------------|--------|------------|------------|----------------|----------|
| User            | UC-001 | UC-005     | UC-006     | UC-007         | Full     |
| Project         | UC-010 | UC-011     | UC-012     | UC-NEW-01      | Full     |
| Report          | UC-020 | UC-021     | —          | —              | Partial  |

## Cross-Cutting Findings

### FINDING-001: [Short title]

- **Type:** Entity Conflict | Dependency Gap | Traceability Gap | Business Rule Conflict |
           Duplicate UC | Missing Seed Data | Actor Overload | MoSCoW Inversion
- **Severity:** High | Medium | Low
- **Affected:** [UC IDs, entity names, FR IDs]
- **Description:** [What is wrong or missing]
- **Recommendation:** [Specific action]
- **Confidence:** HIGH CONFIDENCE | CRITICAL AMBIGUITY

[Repeat for each finding]

## Critical Questions

[Questions that emerged from cross-cutting analysis, max 5]

## Global MoSCoW Distribution

| Category              | Count | % of Total | FRs |
|-----------------------|-------|------------|-----|
| Must have (M)         |       |            | FR-001, FR-002, ... |
| Should have (S)       |       |            | FR-003, ... |
| Could have (C)        |       |            | FR-010, ... |
| Won't have (W)        |       |            | FR-014, ... |
| Unclassified          |       |            | [if any remain] |

**Priority inversions:** [list any Must-have FRs that depend on Could/Won't-have FRs, or "None"]

## Summary

| Metric                  | Count |
|-------------------------|-------|
| Total entities          |       |
| Full CRUD coverage      |       |
| Partial CRUD coverage   |       |
| Total FRs               |       |
| Mapped FRs              |       |
| Orphan FRs              |       |
| Total UCs (undelivered) |       |
| Mapped UCs              |       |
| Orphan UCs              |       |
| Cross-cutting findings  |       |
| MoSCoW inversions       |       |

4. Launch a Nexa PO agent (same persona as Step 2c) to review the cross-cutting findings.

   Agent prompt: Same as Step 2c, but replace the cluster analysis input with docs/engineering/cross-cutting-analysis.md. The Nexa PO agent reviews each finding's recommendation and each critical question using the same CONFIDENT/NEEDS_HUMAN and AGREE/CHALLENGE/APPROVE/DEFER tagging. Write the output to docs/engineering/cross-cutting-po-review.md.

5. Merge Nexa PO answers into the cross-cutting analysis document (same approach as Step 2c-bis): update docs/engineering/cross-cutting-analysis.md to include Nexa PO verdicts inline next to each finding's recommendation and each critical question, so the document is self-contained.

6. Present to the user only NEEDS_HUMAN items, challenges, and a summary of confident decisions (same reduced-scope approach as Step 2d), quoting Q&A pairs from the merged document.

7. Revise if needed (same approach as Step 2e).

8. Apply approved changes to living documents.

9. Update progress manifest — mark cross-cutting analysis as complete.

---

Phase 4: Finalize

1. Update docs/engineering/progress.md:

# Requirements Engineering Progress

**Started:** YYYY-MM-DD
**Completed:** YYYY-MM-DD
**Status:** Complete

## Summary

- **Clusters processed:** [count]
- **Use cases analyzed:** [count]
- **Requirements added:** [count]
- **Requirements refined:** [count]
- **Requirements MoSCoW-classified:** [count] (M: [n] · S: [n] · C: [n] · W: [n])
- **Entities added:** [count]
- **Attributes added:** [count]
- **Use cases added:** [count]
- **Cross-cutting findings resolved:** [count]

## Clusters

| # | Cluster Name       | Use Cases                      | Status   | Completed  |
|---|--------------------|--------------------------------|----------|------------|
| 1 | Authentication     | UC-001, UC-002, UC-003, UC-004 | Complete | YYYY-MM-DD |
| 2 | Project Management | UC-010..UC-014, UC-NEW-01      | Complete | YYYY-MM-DD |
| 3 | Reporting          | UC-020..UC-022                 | Complete | YYYY-MM-DD |

## Cross-Cutting Analysis

- **Status:** Complete
- **Findings:** [count] ([count] resolved, [count] deferred)

## Next Steps

The project is ready for `/sprint-prepare`.

2. Print the final summary to the user:

## Requirements Engineering Complete

**[X] clusters processed, [Y] use cases analyzed**

| Change Type              | Count |
|--------------------------|-------|
| Requirements added       |       |
| Requirements refined     |       |
| MoSCoW: Must have        |       |
| MoSCoW: Should have      |       |
| MoSCoW: Could have       |       |
| MoSCoW: Won't have       |       |
| Entities added           |       |
| Attributes added         |       |
| Use cases added          |       |
| Relationships added      |       |

**Living documents updated:**
- `docs/requirements.md`
- `docs/entity_model.md`
- `docs/use_cases.puml`

**Engineering artifacts:**
- `docs/engineering/progress.md`
- `docs/engineering/cluster-*-analysis.md`
- `docs/engineering/cluster-*-po-review.md`
- `docs/engineering/cross-cutting-analysis.md`
- `docs/engineering/cross-cutting-po-review.md`

**Recommended next step:** `/sprint-prepare` to scope your first sprint.