feat(worker+plan): add Phase 1.5 Investigation and investigation targets template

Add Phase 1.5 to worker.md between Re-anchor and TDD/Implement phases.
Worker reads Required investigation target files before coding, greps for
similar functionality, then proceeds. Skips gracefully when no targets.

Update plan skill task spec template with ## Investigation targets section
(Required/Optional structure). Add good/bad examples to examples.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

agents/worker.md

@@ -219,6 +219,40 @@ git diff --stat HEAD 2>/dev/null || true
 Save `GIT_BASELINE_REV` — you'll use it in Phase 5 to generate workspace change evidence.
 <!-- /section:core -->
 
+<!-- section:core -->
+## Phase 1.5: Pre-implementation Investigation
+
+**If the task spec contains `## Investigation targets` with content, execute this phase. Otherwise skip to Phase 2a/2.**
+
+1. **Read every Required file** listed before writing any code. Note:
+   - Patterns to follow (function signatures, naming conventions, structure)
+   - Constraints discovered (validation rules, type contracts, env requirements)
+   - Anything surprising that might affect your approach
+
+2. **Similar functionality search** — before writing new code:
+   ```bash
+   # Search for functions/modules that do similar things
+   # Use terms from the task description + acceptance criteria
+   grep -r "<key domain term>" --include="*.rs" --include="*.ts" --include="*.py" -l src/
+   ```
+   If similar functionality exists, pick one:
+   - **Reuse**: Use the existing code directly
+   - **Extend**: Modify existing code to support the new case
+   - **New**: Create new code (justify why existing isn't suitable)
+
+   Report what you found:
+   ```
+   Investigation results:
+   - Found: `existingHelper()` in src/utils.ts:23 — reusing
+   - Found: `src/routes/api.ts:45` — following this pattern
+   - No existing implementation found — creating new
+   ```
+
+3. Read **Optional** files as needed based on Step 1 findings.
+
+4. Continue to Phase 2a/2 only after investigation is complete.
+<!-- /section:core -->
+
 <!-- section:tdd -->
 ## Phase 2a: TDD Red-Green (if TDD_MODE=true)
 

skills/flow-code-plan/examples.md

@@ -332,6 +332,43 @@ flowchart LR
 
 ---
 
+## Good vs Bad: Investigation Targets
+
+### ✅ GOOD: Specific paths with purpose
+
+```markdown
+## Investigation targets
+**Required** (read before coding):
+- `flowctl/crates/flowctl-cli/src/commands/task/mod.rs:170-177` — existing task spec template to extend
+- `flowctl/crates/flowctl-cli/src/commands/task/query.rs:15-82` — `--desc`/`--accept` pattern to follow
+
+**Optional** (reference as needed):
+- `flowctl/crates/flowctl-core/src/types.rs:305-325` — phase registry structure
+```
+
+**Why it works**: Exact paths with line ranges. Clear Required vs Optional. Brief purpose descriptions. Worker reads these before coding, grounding implementation in real patterns.
+
+### ❌ BAD: Vague or overloaded targets
+
+```markdown
+## Investigation targets
+- `src/` — look at the source code
+- `tests/` — check the tests
+- `lib/utils.ts` — might be useful
+- `src/auth/oauth.ts`
+- `src/auth/session.ts`
+- `src/auth/middleware.ts`
+- `src/auth/types.ts`
+- `src/auth/index.ts`
+- `src/auth/helpers.ts`
+- `src/auth/validators.ts`
+- `src/auth/errors.ts`
+```
+
+**Why it's bad**: No Required/Optional labels. Vague descriptions ("might be useful"). Directory-level paths waste context. Too many targets (11) — worker reads everything and remembers nothing. Max 5-7 targets per task.
+
+---
+
 ## Summary
 
 | Include in specs | Don't include |
@@ -342,3 +379,4 @@ flowchart LR
 | Recent/surprising APIs | Obvious patterns |
 | Non-obvious gotchas | Every function body |
 | Acceptance criteria | Redundant details |
+| Investigation targets (Required/Optional) | Vague directory paths |

skills/flow-code-plan/steps.md

@@ -282,6 +282,14 @@ Default to standard unless complexity demands more or less.
    - Follow pattern at `src/example.ts:42`
    - Reuse `existingHelper()` from `lib/utils.ts`
 
+   ## Investigation targets
+   **Required** (read before coding):
+   - `src/auth/oauth.ts` — existing OAuth flow to extend
+   - `src/middleware/session.ts:23-45` — session validation pattern
+
+   **Optional** (reference as needed):
+   - `src/auth/*.test.ts` — existing test patterns
+
    ## Key context
    [Only for recent API changes, surprising patterns, or non-obvious gotchas]
    [If stack config exists, include relevant framework conventions here]
@@ -291,6 +299,13 @@ Default to standard unless complexity demands more or less.
    - [ ] Criterion 2
    ```
 
+   **Investigation targets rules:**
+   - Max 5-7 targets per task — enough to ground the worker, not so many it wastes context
+   - Use exact file paths with optional line ranges (e.g., `src/auth.ts:23-45`)
+   - **Required** = must read before implementing. **Optional** = helpful reference
+   - Auto-populated from repo-scout/context-scout findings in Step 1 research
+   - If no relevant files found by scouts, leave the section empty (worker skips Phase 1.5)
+
    **Layer field**: If stack config is set, tag each task with its primary layer. This helps the worker select the right guard commands (e.g., `pytest` for backend, `pnpm test` for frontend). Full-stack tasks run all guards.
 
 7. Add task dependencies (if not already set via `--deps`):