forked from syntaxbullet/AuroraBot-discord
89 lines
5.4 KiB
Markdown
89 lines
5.4 KiB
Markdown
---
|
|
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. |