AuroraBot-discord/.agent/workflows/map-impact.md

description

description
Analyzes the codebase to find dependencies and side effects related to a specific ticket.

WORKFLOW: Dependency Architect & Blast Radius Analysis

1. High-Level Goal

Perform a deterministic "Blast Radius" analysis for a code change defined in a Jira/Linear-style ticket. The agent will identify direct consumers, side effects, and relevant test suites, then append a structured "Impact Analysis" section to the original ticket file to guide developers and ensure high-velocity execution without regressions.

2. Assumptions & Clarifications

• Location: Tickets are stored in the ./tickets/ directory as Markdown files.
• Code Access: The agent has full read access to the project root and subdirectories.
• Scope: Dependency tracing is limited to "one level deep" (direct imports/references) unless a global configuration or core database schema change is detected.
• Ambiguity Handling: If "Suggested Affected Files" are missing from the ticket, the agent will attempt to infer them from the "Acceptance Criteria" logic; if inference is impossible, the agent will halt and request the file list.

3. Stage Breakdown

Stage 1: Ticket Parsing & Context Extraction

• Purpose: Extract the specific files and logic constraints requiring analysis.
• Inputs: A specific ticket filename (e.g., ./tickets/TASK-123.md).
• Actions:
  1. Read the ticket file.
  2. Extract the list of "Suggested Affected Files".
  3. Extract keywords and logic from the "Acceptance Criteria".
  4. Validate that all "Suggested Affected Files" exist in the current codebase.
• Outputs: A JSON object containing the target file list and key logic requirements.
• Persistence Strategy: Save extracted data to /temp/context.json.

Stage 2: Recursive Dependency Mapping

• Purpose: Identify which external modules rely on the target files.
• Inputs: /temp/context.json.
• Actions:
  1. For each file in the target list, perform a search (e.g., grep or AST walk) for import statements or references in the rest of the codebase.
  2. Filter out internal references within the same module (focus on external consumers).
  3. Detect if the change involves shared utilities (e.g., utils/, common/) or database schemas (e.g., prisma/schema.prisma).
• Outputs: A list of unique consumer file paths and their specific usage context.
• Persistence Strategy: Save findings to /temp/dependencies.json.

Stage 3: Test Suite Identification

• Purpose: Locate the specific test files required to validate the change.
• Inputs: /temp/context.json and /temp/dependencies.json.
• Actions:
  1. Search for files following patterns: [filename].test.ts, [filename].spec.js, or within __tests__ folders related to affected files.
  2. Identify integration or E2E tests that cover the consumer paths identified in Stage 2.
• Outputs: A list of relevant test file paths.
• Persistence Strategy: Save findings to /temp/tests.json.

Stage 4: Risk Hotspot Synthesis

• Purpose: Interpret raw dependency data into actionable risk warnings.
• Inputs: All files in /temp/.
• Actions:
  1. Analyze the volume of consumers; if a file has >5 consumers, flag it as a "High Impact Hotspot."
  2. Check for breaking contract changes (e.g., interface modifications) based on the "Acceptance Criteria".
  3. Formulate specific "Risk Hotspot" warnings (e.g., "Changing Auth interface affects 12 files; consider a wrapper.").
• Outputs: A structured Markdown-ready report object.
• Persistence Strategy: Save final report data to /temp/final_analysis.json.

Stage 5: Ticket Augmentation & Finalization

• Purpose: Update the physical ticket file with findings.
• Inputs: Original ticket file and /temp/final_analysis.json.
• Actions:
  1. Read the current content of the ticket file.
  2. Generate a Markdown section titled ## Impact Analysis (Generated: 2026-01-09).
  3. Append the Direct Consumers, Test Coverage, and Risk Hotspots sections.
  4. Write the combined content back to the original file path.
• Outputs: Updated Markdown ticket.
• Persistence Strategy: None (Final Action).

4. Data & File Contracts

• State File (/temp/state.json): - affected_files: string[]
  • consumers: { path: string, context: string }[]
  • tests: string[]
  • risks: string[]
• File Format: All /temp files must be valid JSON.
• Ticket Format: Standard Markdown. Use ### for sub-headers in the generated section.

5. Failure & Recovery Handling

• Missing Ticket: If the ticket path is invalid, exit immediately with error: "TICKET_NOT_FOUND".
• Zero Consumers Found: If no external consumers are found, state "No external dependencies detected" in the report; do not fail.
• Broken Imports: If AST parsing fails due to syntax errors in the codebase, fallback to grep for string-based matching.
• Write Permission: If the ticket file is read-only, output the final Markdown to the console and provide a warning.

6. Final Deliverable Specification

• Format: The original ticket file must be modified in-place.
• Content:
  • Direct Consumers: Bulleted list of [File Path]: [Usage description].
  • Test Coverage: Bulleted list of [File Path].
  • Risk Hotspots: Clear, one-sentence warnings for high-risk areas.
• Quality Bar: No hallucinations. Every file path listed must exist in the repository. No deletions of original ticket content.