Instruction file imported from gargislalom/so-ai-training-101-pnw-team2 (.github/instructions/intake/workflows/requirement-arch-analysis.instructions.md). Copyright stays with the author.

Requirement & Architecture Analysis

When to Use

• Starting estimation analysis for a system component (FC, REO, Collections, etc.)
• Validating that epics/stories align with architecture service boundaries
• Producing a unified backlog-ready analysis with classification and prioritization
• Identifying cross-cutting gaps between domains

Inputs to Gather

Before starting, locate these files for the target component:

1. Architecture doc: docs/architecture/{Component Name}.md - service boundaries, domain events, ADRs, service flows
2. Table design: docs/architecture/database/service-{component}-table-design.md - DynamoDB entities
3. State machines: docs/architecture/state-machines/{component}-state-machines.md
4. Domain events: docs/architecture/Domain Events.md
5. PRD: requirements/features/{component}-management/design/PRD - {Component} Management.md
6. Epic files: requirements/features/{component}-management/epics/*.md
7. Sankey/estimation data: requirements/features/{component}-management/sankey-diagram.html or story-point-estimation-*.md
8. Workshop sessions: docs/discussions/{Component}/ and docs/discussions/Workshop/*/Summary/*{Component}*
9. Existing gap analysis: docs/backlogs/*{component}* or requirements/features/{component}-management/gap-analysis-*.md
10. Workshop requirements summary: requirements/features/{component}-management/eureka-workshop-requirements-summary.md
11. reference /kb-query: /kb-querry

Analysis Workflow

Step 1: Session Inventory

Read all session summaries for the component. For each session extract:

• Date, name, participants, duration
• Feedback item counts (NR/E/RC/architecture constraint/open question)
• Key requirements with source citation (date + session name)
• Cross-cutting concerns with affected domains

Step 2: Architecture Alignment

Map every story to the architecture framework:

A. Service Ownership - Assign each story to its owning service based on the architecture doc's service boundaries.

B. Domain Event Coverage - List every published/consumed event. For each, identify implementing stories. Flag events with no story.

C. Data Entity Coverage - List every DynamoDB entity. For each, check CRUD/lifecycle story coverage. Flag incomplete coverage.

D. State Machine Coverage - Check key state transitions for implementation stories.

E. Capability Gap Detection - List architecture-defined capabilities (reports, workflows, cascades). Check each for corresponding stories.

F. Epic Boundary Analysis - For each epic, list which services its stories touch. Flag multi-service epics and recommend splitting/consolidating.

Step 3: Story Classification

Classify each story across four dimensions:

Owning Service: Primary service per architecture doc. Options vary by component.

Automation Type:

• Full Automation - Currently manual, fully automated in <TEAM_NAME>
• Semi-to-Auto - Partially automated in legacy, fully automated
• Manual Retained - Remains manual with improved UI/UX
• System-Enforced - New enforcement replacing human discipline

Legacy/New:

• Legacy Replacement - Exists in AMS4/ILS, being rebuilt
• Legacy Enhancement - Exists in legacy, significantly improved
• New Automation (In-System) - Done outside the system today (Excel, email, paper)
• New Automation (Net-New) - Doesn't exist anywhere today

Priority (definitions may be refined per component):

• Critical - Required for regulatory/compliance loan servicing
• High - Currently automated in AMS4/ILS, must replace for parity
• Medium - New automation, significant efficiency gain
• Low - New automation, low efficiency gain
• Lowest - Excel is equal efficiency

Step 4: Unified Document Assembly

Create {component}-estimation-analysis-{date}.md with these sections:

• Part A: Session synthesis and gap analysis (inventory table, consolidated features, cross-cutting concerns, high-risk items)
• Part B: Architecture alignment (service ownership, event/entity/state machine coverage, restructuring recommendations)
• Part C: Unified estimation tables (one per epic, all dimensions per story row)
• Part D: Aggregate analysis (stats by dimension, release wave groupings, dependency map)
• Part E: Cross-cutting gap analysis (missing stories/events for cross-domain integration)

Step 5: HTML Visualization

Create {component}-estimation-analysis-{date}.html with:

• Plotly Sankey diagram with tab-switchable color coding (priority, automation, legacy/new, release wave)
• Summary stat cards computed from embedded data
• Hover details showing all classification dimensions

Output Table Schema

The core deliverable is a unified story table per epic:

Every row must have a Source(s) citation with date + session name.

Validation Checklist

Before finalizing, verify:

• All session summaries read and cited
• Every story has an owning service assignment
• Every architecture domain event has a coverage status
• Every DynamoDB entity has CRUD coverage status
• Epic restructuring recommendations provided for multi-service epics
• Aggregate stats sum correctly (SP totals = feature total)
• Cross-cutting gaps reference specific affected epics and owning services
• HTML visualization renders all stories with correct color coding

Reference

For detailed column definitions and classification examples, see reference.md.