feat(spec-writing): add impact analysis to prevent missing affected code

Problem: When writing specs for refactoring tasks that modify shared
constants or types, the current workflow only searches for "reusable"
code, not ALL affected code. This caused specs to miss critical areas
like duplicate definitions in different packages (e.g., crawler having
its own SUPPORTED_LANGUAGES while shared package has another).

Solution: Add three layers of impact analysis:

1. write-spec.md - New Step 2.5 "Impact Analysis":
   - Search for ALL usages of constants/types being modified
   - Detect duplicate definitions across packages (RED FLAG)
   - Find hardcoded values that should use constants
   - Document all affected packages/modules

2. research-spec.md - New impact analysis question:
   - Ask users about OTHER packages that might be affected
   - Specifically mention crawler, scripts, config files, tests
   - Record affected areas for spec-writer to investigate

3. create-tasks-list.md - New Step 1.5 "Verify Spec Completeness":
   - Independent grep search before creating tasks
   - Compare grep results with files mentioned in spec
   - Flag and document any gaps found
   - Create additional task groups for missing areas

This ensures refactoring specs capture ALL code that needs updates,
preventing production issues from partially applied changes.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Perlover

profiles/default/workflows/implementation/create-tasks-list.md

@@ -3,9 +3,10 @@
 ## Core Responsibilities
 
 1. **Analyze spec and requirements**: Read and analyze the spec.md and/or requirements.md to inform the tasks list you will create.
-2. **Plan task execution order**: Break the requirements into a list of tasks in an order that takes their dependencies into account.
-3. **Group tasks by specialization**: Group tasks that require the same skill or stack specialization together (backend, api, ui design, etc.)
-4. **Create Tasks list**: Create the markdown tasks list broken into groups with sub-tasks.
+2. **Verify spec completeness**: For refactoring tasks, independently verify all affected code is covered in the spec.
+3. **Plan task execution order**: Break the requirements into a list of tasks in an order that takes their dependencies into account.
+4. **Group tasks by specialization**: Group tasks that require the same skill or stack specialization together (backend, api, ui design, etc.)
+5. **Create Tasks list**: Create the markdown tasks list broken into groups with sub-tasks.
 
 ## Workflow
 
@@ -17,6 +18,56 @@ Read each of these files (whichever are available) and analyze them to understan
 
 Use your learnings to inform the tasks list and groupings you will create in the next step.
 
+### Step 1.5: Verify Spec Completeness (for refactoring tasks)
+
+**CRITICAL:** Before creating tasks, verify the spec has identified ALL affected code. This prevents missing critical updates that could break the application.
+
+**When to perform verification:**
+- The spec involves modifying shared constants, types, or patterns
+- The spec involves renaming or changing values used across files
+- The spec mentions any kind of refactoring
+
+**How to verify:**
+
+1. **Identify key constants/types from the spec:**
+   Extract the main constants, types, or patterns being modified from the spec.
+
+2. **Run independent impact verification:**
+   ```bash
+   # For each constant/type being modified, search entire codebase
+   grep -r "CONSTANT_NAME" --include="*.ts" --include="*.tsx" --include="*.vue" . | wc -l
+
+   # List unique directories with matches
+   grep -r "CONSTANT_NAME" --include="*.ts" | cut -d':' -f1 | xargs -I{} dirname {} | sort -u
+   ```
+
+3. **Compare against spec:**
+   - Count files/packages mentioned in spec
+   - Compare with grep results
+   - If grep finds MORE files/packages than spec mentions, the spec may be INCOMPLETE
+
+4. **Check for duplicate definitions:**
+   ```bash
+   # Detect if same constant is defined in multiple places
+   grep -rn "export const CONSTANT_NAME" --include="*.ts" .
+   ```
+   If duplicates exist but aren't mentioned in spec, flag this.
+
+5. **If gaps found:**
+   - Document the missing files/packages discovered
+   - Create additional task groups to address them
+   - Include a note in tasks.md about the gaps found
+
+**Example gap documentation in tasks.md:**
+```markdown
+### Note: Additional Files Discovered
+
+During task creation, impact analysis found the following files not mentioned in spec:
+- `packages/server/src/crawler/config.ts` - contains duplicate CONSTANT_NAME definition
+- `packages/server/src/scripts/utils.ts` - hardcoded value 'xyz'
+
+These have been added as Task Group X.
+```
 
 ### Step 2: Create Tasks Breakdown
 
@@ -188,6 +239,8 @@ Recommended implementation sequence:
 ## Important Constraints
 
 - **Create tasks that are specific and verifiable**
+- **Verify spec completeness for refactoring tasks:** Run independent grep searches to find all affected files, not just those mentioned in spec
+- **Flag gaps discovered:** If your impact analysis finds files not in the spec, document them and create task groups to address them
 - **Group related tasks:** For example, group back-end engineering tasks together and front-end UI tasks together.
 - **Limit test writing during development**:
   - Each task group (1-3) should write 2-8 focused tests maximum

profiles/default/workflows/specification/research-spec.md

@@ -74,6 +74,20 @@ Are there existing features in your codebase with similar patterns we should ref
 
 Please provide file/folder paths or names of these features if they exist.
 
+**Impact Analysis (for refactoring/modification tasks):**
+If this feature involves changing existing constants, types, or shared code, I need to identify ALL affected areas to avoid missing critical updates:
+
+- Are there any OTHER packages or modules that define or use the same constants/types?
+- Are there any hardcoded values in the codebase that should be updated?
+- Which areas beyond the obvious ones might be affected?
+  - Backend services?
+  - Crawler/background jobs?
+  - Scripts and utilities?
+  - Configuration files?
+  - Tests?
+
+Please list any areas you know use the affected constants/types that I should investigate.
+
 **Visual Assets Request:**
 Do you have any design mockups, wireframes, or screenshots that could help guide the development?
 
@@ -182,6 +196,17 @@ Use the following structure and do not deviate from this structure when writing
 [If user provided no similar features]
 No similar existing features identified for reference.
 
+### Impact Analysis
+[Based on user's response about affected areas - CRITICAL for refactoring tasks]
+
+**Affected Areas Identified by User:**
+- Package/Module: [Name] - Reason: [why it's affected]
+- Hardcoded values: [locations mentioned by user]
+- Additional areas: [crawler, scripts, config files, etc.]
+
+[If user provided no impact information OR this is a new feature (not refactoring)]
+No additional impact areas identified. Note: spec-writer should still perform independent impact analysis.
+
 ### Follow-up Questions
 [If any were asked]
 
@@ -251,12 +276,15 @@ Ready for specification creation.
 ## Important Constraints
 
 - **MANDATORY**: Always run bash command to check visuals folder after receiving user answers
+- **MANDATORY**: Always ask about impact analysis for refactoring tasks - which other areas use the same constants/types
 - DO NOT write technical specifications for development. Just record your findings from information gathering to this single file: `[spec-path]/planning/requirements.md`.
 - Visual check is based on actual file(s) found via bash, NOT user statements
 - Check filenames for low-fidelity indicators and clarify design intent if found
 - Ask about existing similar features to promote code reuse
+- Ask about affected areas beyond obvious ones (crawler, scripts, config files, tests)
 - Keep follow-ups minimal (1-3 questions max)
 - Save user's exact answers, not interpretations
 - Document all visual findings including fidelity level
 - Document paths to similar features for spec-writer to reference
+- Document all affected areas mentioned by user for spec-writer's impact analysis
 - OUTPUT questions and STOP to wait for orchestrator to relay responses

profiles/default/workflows/specification/write-spec.md

@@ -4,7 +4,8 @@
 
 1. **Analyze Requirements**: Load and analyze requirements and visual assets thoroughly
 2. **Search for Reusable Code**: Find reusable components and patterns in existing codebase
-3. **Create Specification**: Write comprehensive specification document
+3. **Impact Analysis**: Find ALL code affected by this change (critical for refactoring)
+4. **Create Specification**: Write comprehensive specification document
 
 ## Workflow
 
@@ -44,6 +45,53 @@ Use appropriate search tools and commands for the project's technology stack to
 
 Document your findings for use in the specification.
 
+### Step 2.5: Impact Analysis - Find All Affected Code
+
+**CRITICAL:** Before creating the specification, perform comprehensive impact analysis to find ALL code that will be affected by this change. This is especially important for refactoring tasks that modify shared constants, types, or patterns.
+
+**When to perform impact analysis:**
+- Modifying shared constants or type definitions
+- Renaming or changing values used across multiple files
+- Refactoring code that may have duplicates in different packages
+- Changing APIs, database schemas, or configuration formats
+
+**How to perform impact analysis:**
+
+1. **Search for constant/type usages:**
+   ```bash
+   # Find all files using the constants/types being modified
+   grep -r "CONSTANT_NAME" --include="*.ts" --include="*.tsx" --include="*.vue" .
+   grep -r "TypeName" --include="*.ts" --include="*.tsx" .
+   ```
+
+2. **Check for duplicate definitions:**
+   ```bash
+   # Detect if the same constant is defined in multiple places (this is a RED FLAG)
+   grep -rn "export const CONSTANT_NAME" --include="*.ts" .
+   grep -rn "export type TypeName" --include="*.ts" .
+   ```
+   If duplicates are found, they MUST be consolidated in the spec.
+
+3. **Find hardcoded values:**
+   ```bash
+   # Search for hardcoded values that should use the constant
+   grep -rn "'literal_value'" --include="*.ts" --include="*.tsx" --include="*.vue" .
+   ```
+
+4. **Identify all packages/modules affected:**
+   ```bash
+   # List unique directories with matches
+   grep -r "CONSTANT_NAME" --include="*.ts" | cut -d':' -f1 | xargs -I{} dirname {} | sort -u
+   ```
+
+**Document your findings:**
+- Total files affected (count)
+- Duplicate definitions found (these MUST be listed for consolidation)
+- Hardcoded values found (these MUST be listed for refactoring)
+- All packages/modules requiring updates
+
+**Include in specification:** Add a "Files Requiring Modification" section OR expand "Existing Code to Leverage" to include all affected files, not just reusable ones.
+
 ### Step 3: Create Core Specification
 
 Write the main specification to `agent-os/specs/[current-spec]/spec.md`.
@@ -93,7 +141,9 @@ Follow this structure exactly when creating the content of `spec.md`:
 ## Important Constraints
 
 1. **Always search for reusable code** before specifying new components
-2. **Reference visual assets** when available
-3. **Do NOT write actual code** in the spec
-4. **Keep each section short**, with clear, direct, skimmable specifications
-5. **Do NOT deviate from the template above** and do not add additional sections
+2. **Always perform impact analysis** for refactoring tasks - find ALL affected files, not just similar ones
+3. **Check for duplicate definitions** - if the same constant/type exists in multiple packages, flag it for consolidation
+4. **Reference visual assets** when available
+5. **Do NOT write actual code** in the spec
+6. **Keep each section short**, with clear, direct, skimmable specifications
+7. **Do NOT deviate from the template above** and do not add additional sections