Instruction file imported from gargislalom/so-ai-training-101-pnw-team2 (.github/instructions/intake/workflows/workshop-update-tech-refinement.instructions.md). Copyright stays with the author.

Process Daily Tech Refinement Session

Processes a Daily Tech Refinement session where the team walks through the existing legacy architecture and technology, discusses how it needs to work in the future state, and identifies gotchas and technical integration points. Generates requirement update proposals for PRDs, creates/updates epics directly, and validates all assumptions.

Does NOT modify prototypes (XD team owns prototype updates) or directly modify PRDs. The goal is to capture architectural constraints, integration realities, and technical decisions that shape requirements for the future state application replacing the legacy system.

Input

Primary (one of):

• A transcript file (.vtt, .docx, .txt) from the tech refinement session
• Pasted notes or bullet points summarizing the technical discussion
• A reference to a specific domain (Bankruptcy, Collections, Foreclosure, Loss Mitigation, REO, Warnings)

Optional - Observer Notes:

• One or more files (.md, .txt, .docx) containing notes taken by meeting observers
• Observer notes capture technical context the transcript misses: whiteboard diagrams, architecture sketches, system names mentioned in passing, and concerns expressed through emphasis rather than explicit statements
• When provided, observer notes are cross-referenced during extraction to catch technical constraints that were diagrammed or implied rather than verbalized

Multi-Agent Workflow

Phase 1: Context Discovery (parallel agents)

Agent 1 - Requirements & Architecture Discovery (explore): Scan requirements/features/ for the identified domain. Collect:

• All PRDs (design/PRD - *.md and *-prd.md)
• All epics (epics/*.md) - focus on technical sections (Architecture, Data Model, API Specs, Domain Events, NFRs)
• Architecture docs (*-architecture.md, *-architecture-requirements.md)
• Clarifications and open questions (*-clarifications.md, *-open-questions.md)

Also scan docs/architecture/conventions/ for:

• Context objects convention
• Event-driven messaging convention
• Logging convention
• Any other conventions referenced by existing domain epics

Return structured inventory with file paths, technical scope of each document, and current architectural decisions.

Agent 2 - Cross-Domain Technical Context (explore): Identify technical dependencies and integration points:

• Scan requirements/features/data-platform-integration/ for data contract governance
• Scan requirements/features/workflow-management/ for workflow engine dependencies
• Scan requirements/features/command-center-task-management/ for task management integration
• Scan requirements/features/communication-hub/ for notification dependencies
• Check docs/architecture/ for system-wide architectural patterns

Return a dependency map of cross-domain technical integration points relevant to the discussion domain.

Agent 3 - KB Technical Enrichment (shell): For each technical question, concern, or ambiguity in the discussion, query the knowledge base:

aws bedrock-agent-runtime retrieve \
  --profile local-development \
  --knowledge-base-id JOVETQBNBE \
  --retrieval-query text="[technical query - e.g., 'legacy bankruptcy payment processing architecture integration']" \
  --retrieval-configuration 'vectorSearchConfiguration={numberOfResults=5}' \
  --query 'retrievalResults[].content.text' \
  --output text

Use required_permissions: ["all"] for network access. Focus queries on:

• Prior architectural decisions
• Legacy system integration patterns
• Technical constraints from client infrastructure
• Performance and scalability decisions

Return relevant context with source attribution, flag gaps where KB returned insufficient context.

Troubleshooting - Expired AWS Token: If the query fails with an expired token or credentials error, ensure the command is using --profile local-development. If it still fails, run aws sso login --profile local-development and alert the user to complete the SSO sign-in from their browser before retrying.

Phase 2: Feedback Extraction & Technical Analysis

Step 1 - Atomic Extraction (MANDATORY)

Perform exhaustive line-by-line extraction of every distinct technical concern, constraint, architectural insight, or recommendation from the transcript. Walk through each timestamp block sequentially.

If observer notes are provided: After transcript extraction, scan observer notes for uncaptured items - architecture diagrams, system constraints from sidebar conversations, technical concerns expressed through emphasis. Add these tagged with (Source: Observer Notes). Where observer notes add context to an existing item, append that context.

Decomposition rules:

• If a single utterance contains multiple distinct technical points, each becomes its own item. "X needs to be normalized AND Y needs an SLA" = two items.
• Separate legacy system behavior from future state recommendations even when discussed together
• Separate data model insights from architectural pattern recommendations
• Separate NFRs (performance targets, SLAs) from the architectural decisions they drive
• Separate gotchas/warnings from the integration requirements they imply
• When a speaker identifies multiple fields, entities, services, or integration points, each is a separate item

Output: Numbered list of atomic items with: item number, speaker name + timestamp range, specific technical point (one sentence), direct quote.

Step 2 - Extraction Verification (MANDATORY)

Re-scan transcript beginning to end and verify:

• Every timestamp block contributed at least one item (or was facilitator-only)
• No compound utterances left un-split
• Total item count is plausible for the session length

Add missed items before proceeding.

Step 3 - Feedback Classification

Categorize each atomic item. Apply the first matching category:

• Legacy Architecture Insight - How the existing system works; essential context for the replacement
• Architecture Constraint - Limits on how the future state can be built (client infra, compliance, security)
• Integration Requirement - New or modified integration points with client systems, legacy systems, or third parties
• NFR Update - Performance, scalability, reliability, security requirements (with specific targets where stated)
• Data Model Impact - Schema changes, new entities, field modifications, data migration considerations
• API Specification - New endpoints, contract changes, versioning concerns
• Domain Event Impact - New events, event payload changes, event routing
• Gotcha / Technical Risk - Known pitfalls, edge cases, or risks from legacy system behavior that the future state must account for
• Migration Consideration - Data migration, cutover, or coexistence concerns for the legacy-to-future-state transition
• Out of Scope - Technical discussion items not affecting current requirements

Step 4 - Architecture Decision Records

For each significant technical decision made or confirmed during the session, capture:

• Decision context and drivers (including legacy constraints)
• Options considered (if discussed)
• Decision outcome
• Consequences and trade-offs
• Affected components and documents

Phase 3: Risk & Consistency Analysis (parallel agents)

Agent 4 - Technical Risk Assessment (generalPurpose): Review the technical discussion against existing architecture and identify:

• Feasibility risks: Discussion suggesting approaches that conflict with established architecture conventions
• Integration risks: New integration points creating coupling between services
• Performance risks: Requirements that may not meet NFR targets
• Security risks: Discussion affecting authentication, authorization, or data privacy
• Data contract risks: Schema changes impacting Data Engineering consumption
• Migration risks: Changes requiring data migration or backward compatibility
• Dependency risks: Technical discussion creating blocking dependencies across teams or features
• Legacy coupling risks: Future state design that inadvertently preserves legacy limitations

Format as risk register with severity (High/Medium/Low), technical description, affected architecture components, recommended mitigation.

Agent 5 - Technical Inconsistency Detection (generalPurpose): Cross-reference technical discussion against ALL existing documents and flag:

• Contradictions between discussion and existing architecture conventions in docs/architecture/conventions/
• Contradictions between discussion and existing epic technical specifications
• Discussion that conflicts with prior architectural decisions in meeting summaries
• Discussion that would require changes to already-documented features
• Inconsistencies between technical discussion and PRD-level requirements
• Conflicts between discussion items themselves
• Legacy system behavior described differently than previously documented

Format each with: the item, conflicting document (file path + section), nature of conflict, recommended resolution path.

Phase 4: Requirements Update (sequential, with approval)

Present the following to the user for approval before making changes:

1. Technical discussion summary - Categorized by type
2. Architecture Decision Records - From Phase 2
3. Proposed requirement changes - Grouped by document
4. Risk register - From Agent 4
5. Inconsistencies found - From Agent 5
6. New artifacts needed - New epics, architecture docs, or technical specs
7. Cross-feature dependencies - Technical dependencies across domains

After user approval, execute updates:

PRDs - Generate Requirement Update Proposal (do NOT modify PRDs directly)

Create a proposal document at docs/discussions/Workshop/{date}/Proposals/{date}_{domain}_Tech-Refinement_PRD-Update-Proposal.md:

# Requirement Update Proposal - [Domain] (Tech Refinement)

## Proposal Metadata

| Field | Value |
|-------|-------|
| **Session Type** | Daily Tech Refinement |
| **Session Date** | [date] |
| **Domain** | [domain] |
| **Target PRD** | [PRD filename and path] |
| **Total Proposed Changes** | [count] |
| **Generated By** | AI-assisted extraction from tech refinement session |

## Architecture Decision Records
[ADR entries for decisions made during this session]

## Proposed Changes

### [N]. [Change Title]
- **PRD Section**: [Section number and name]
- **Change Type**: Technical Constraint | NFR Addition | Scope Change | Dependency Addition | Architecture Update
- **Current State**: [What the PRD currently says, or "N/A - new addition"]
- **Proposed Update**: [Exact text or structured content to add/replace]
- **Source**: [Discussion item number, speaker, timestamp]
- **Legacy Context**: [Relevant legacy system behavior driving this change]
- **Future State Rationale**: [Why this matters for the replacement application]

## Deferred Items
[Items noted but not proposed, with technical rationale]

## Assumptions
[Cross-reference to Assumption Register]

Epics - Update Directly

For existing epics:

• Update Architecture section with new constraints or decisions
• Update Data Model section if schema changes identified
• Update API Specifications with new endpoints or contract changes
• Update Domain Events section
• Update NFRs (performance, security, reliability targets)
• Update Integration Points with new dependencies
• Add new stories for technical work identified
• Update Open Questions with resolved and new technical questions
• Add <!-- Workshop Update: [date] - Tech Refinement --> annotations

For new epics (if needed):

• Use template from docs/templates/epic-template-v2.md
• Place in requirements/features/{domain}/epics/
• Reference architecture conventions: logging, event-driven-messaging, context-objects as applicable
• Confirm with user before creation

For architecture docs:

• Update or create {domain}-architecture.md in the feature folder
• Document integration patterns, sequence flows, and component boundaries

Phase 5: Assumption Identification & Validation (MANDATORY)

After all requirement updates and proposals are generated, perform a dedicated assumption audit.

Tech refinement sessions are particularly prone to assumptions about how the legacy system works vs. how participants describe it. Pay special attention to:

Step 1 - Assumption Extraction

Review every requirement generated or updated and extract all assumptions:

• Legacy behavior assumptions - Assumed legacy system behavior based on description rather than direct observation
• Architecture assumptions - Assumed future state architecture patterns or capabilities
• Data assumptions - Assumed data availability, migration feasibility, or format compatibility
• Integration assumptions - Assumed third-party system capabilities or API availability
• Performance assumptions - Assumed performance characteristics of legacy or future state
• Migration assumptions - Assumed feasibility of data migration or cutover approach

Step 2 - Assumption Validation

For each assumption, attempt validation in this order:

1. Check existing PRDs, epics, and architecture docs for confirmation
2. Query KB for supporting or contradicting context
3. Cross-reference against ODR session outputs (observed behavior may confirm or contradict described behavior)

Classify each assumption as:

• Confirmed - Validated against existing documentation or KB (cite source)
• Needs Stakeholder Validation - Requires confirmation from business team
• Needs Technical Validation - Requires confirmation from client technical team or legacy system SME
• Needs ODR Validation - Should be verified through direct observation of the legacy system
• Unresolvable from Available Context - No existing source addresses this; flag for follow-up

Step 3 - Assumption Register

Create a structured register:

Step 4 - User Presentation

Present the assumption register and flag any high-risk unvalidated assumptions. For tech refinement sessions, specifically highlight:

• Assumptions about legacy system behavior that haven't been directly observed (recommend ODR session)
• Assumptions about future state architecture that haven't been formally decided
• Assumptions about data migration feasibility

Phase 6: Output Documents

Technical Refinement Summary

Save to docs/discussions/Workshop/{date}/Summary/{date}_{domain}_Tech-Refinement_Summary.md:

• Session metadata (date, domain, technical participants)
• Categorized technical discussion items
• Architecture decisions made or confirmed
• Legacy system insights captured
• Open technical questions requiring follow-up

Architecture Decision Log

Save to docs/discussions/Workshop/{date}/{date}_{domain}_Architecture-Decisions.md:

• ADR entries for each significant decision
• Context, options, outcome, consequences

Requirement Update Proposal

Save to docs/discussions/Workshop/{date}/Proposals/{date}_{domain}_Tech-Refinement_PRD-Update-Proposal.md (generated in Phase 4)

Assumption Register

Save to docs/discussions/Workshop/{date}/{date}_{domain}_Assumption-Register.md (append if file exists from another session the same day)

Change Log

Append to or create docs/discussions/Workshop/{date}/{date}_{domain}_Change-Log.md:

• Table of documents modified with technical change descriptions
• New documents created
• Deferred items with technical rationale

Risk & Dependency Report

Save to (or append to) docs/discussions/Workshop/{date}/{date}_{domain}_Risks-Dependencies.md:

• Technical risk register
• Cross-feature dependency map
• Integration dependency map
• Inconsistencies found and resolutions

Phase 7: Jira (optional)

After local updates are complete, offer to:

• Create new technical epics in Jira (SPM project) for architecture work identified
• Create spike stories for technical investigations needed
• Add architecture-review and technical-debt labels to relevant tickets

Follow Jira creation rules from create-jira-ticket.md. Confirm with user before creating external artifacts.

CRITICAL: Never generate work estimates (story points, days, weeks, sprints).

Data Contract Impact Assessment (MANDATORY)

Technical refinement sessions frequently affect data contracts. Assess and document impact for every session. Include Data Contract Impact section in all new epics. Flag for DE team review when schema changes are identified.

KB Enrichment Log (MANDATORY)

Every output document MUST include a KB Enrichment Log section per the kb-enrichment.mdc rule.

Architecture Convention References

When updating epics and creating new technical stories, reference these conventions by name (do not copy content):

• Logging: Reference for any epic or story with a code component
• Event-Driven Messaging: Reference for domain events, event publishing, event consumption
• Context Objects: Reference for APIs (creating or calling), DynamoDB operations, domain event handling

Domain-to-Folder Mapping

Mandatory Rules

• NO ESTIMATES: Never generate story points, days, weeks, or sprint assignments
• NO DIRECT PRD EDITS: Generate Requirement Update Proposals; PRDs are updated separately
• Confirm before modifying: Show user a preview of all proposed changes before writing
• Source attribution: Tag all changes with workshop date and "Tech Refinement" session type
• Preserve existing content: Append and annotate, never silently remove existing requirements
• KB-first: Query knowledge base before escalating ambiguities to the user
• Validate assumptions: Every session MUST produce an assumption register
• Convention references: Always reference relevant architecture conventions in new epics/stories
• Legacy-to-future framing: All technical requirements must explicitly connect legacy behavior to future state needs