context-gatherer

name	context-gatherer
description	Phase 0.1 — Automatic codebase scan before PRD generation. Extracts key terms from the user prompt, searches the codebase for related files, identifies existing patterns, and generates context.md in the state directory.
allowed-tools	["Read","Grep","Glob","Write","Bash(mkdir:*)"]

Context Gatherer

Runs automatically as Phase 0.1, before idea-explorer asks its first question. Purpose: ground the entire spec in the actual codebase — not assumptions.

Slug generation

Derive {slug} from the user's prompt before doing anything else:

1. Lowercase the full prompt string
2. Remove punctuation
3. Split into words; skip stop words: a an the to for of in with from and or but is are was
4. Take the first 6 significant words
5. Join with hyphens; truncate to 60 characters

Example:

Prompt: "Allow personal trainers to connect with students after checkout"
Slug:   allow-personal-trainers-connect-students-checkout

When to run

• Always runs before the first idea-explorer question
• If .claude/feature-state/{slug}/context.md already exists: load it (do not re-scan — resume flow)
• Rerun from scratch only when explicitly asked

Step 1: Extract key terms from the user prompt

Parse the user's feature prompt for:

• Entities: nouns that likely map to data models (e.g., "student", "trainer", "subscription")
• Actions: verbs that describe behavior (e.g., "connect", "enroll", "notify", "list")
• Domain words: business-specific terms (e.g., "checkout", "onboarding", "dashboard")

Example:

Prompt: "Allow personal trainers to connect with students after checkout"
Key terms: ["trainer", "student", "connect", "checkout", "personal trainer"]

Step 2: Search the codebase for related files

For each extracted key term, use the Grep tool (not bash grep — Bash is not available for search in this skill):

• Run one Grep call per term, case-insensitive (-i), output_mode: "files_with_matches"
• Glob filter covering source files: *.{ts,tsx,js,swift,rs,py,go}
• Also search test files separately with glob: *{test,spec}*

Deduplicate the file lists across all terms. Score each file by how many distinct terms it matched. Select the 5–10 most relevant files (highest match count + most central paths).

Step 3: Read project context files

Always read these files if they exist:

File	Purpose
./CLAUDE.md	Project-level conventions
./.claude/spec-workflow/PROJECT.md	Project DNA (architecture rules, constraints)
./README.md	Project overview
./AGENTS.md	Agent-specific instructions
./package.json	Node.js dependencies and scripts
./Cargo.toml	Rust dependencies
./Package.swift	Swift dependencies
./go.mod	Go module info

Step 4: Extract existing patterns

From the files identified in Steps 2–3, extract:

Architecture patterns

• What patterns are in use? (MVVM, Repository, Clean Architecture, MVC, etc.)
• Where are they located in the project?

Naming conventions

• How are entities named? (camelCase, snake_case, PascalCase)
• How are files named? (feature-name.ts, FeatureName.swift, etc.)

Similar features

• Is there already a feature similar to what's being requested?
• Which files implement it? What can be reused or extended?

Existing entities related to the prompt

• Do any of the key terms already have implementations?
• What fields, methods, or relationships do they already have?

Step 5: Generate context.md

First, create the state directory so the Write tool doesn't fail:

mkdir -p .claude/feature-state/{slug}

Then write to .claude/feature-state/{slug}/context.md using the Write tool:

## Context Report

Generated: {timestamp}
Prompt: "{original prompt}"

### Related Files Found

- `path/to/file1` — [why it's relevant, e.g., "implements Student entity"]
- `path/to/file2` — [e.g., "Firestore queries for trainer data"]
- `path/to/file3` — [e.g., "authentication middleware used by all API routes"]

### Existing Patterns

- Architecture: MVVM + Repository + Use Cases
- Auth: Firebase Auth — ID token in Authorization header on all routes
- Data: Firestore with soft delete (status: 'archived')
- Naming: Firebase UIDs stored as 'uid' throughout

### Similar Features Already Implemented

- **Student enrollment** at `src/api/students/` — creates Firestore docs via Cloud Function
- **Trainer profile** at `Presentation/Features/Trainer/` — MVVM pattern, fetches from /api/trainers

### Entities Related to Prompt

- **Student** — exists at `src/types/student.ts`, fields: uid, name, email, trainerId?
- **Trainer** — exists at `src/types/trainer.ts`, fields: uid, name, specialization[]
- **checkout** — Cloud Function `handleCheckoutComplete` creates student records after Stripe payment

### Constraints Detected

- Stripe webhook creates student-trainer relationships — any new connection flow should integrate with this
- FCM token not guaranteed — push notifications are optional for all users
- Feature flags via Firebase Remote Config — new user-facing features need a flag

### What DOESN'T Exist (Relevant to Prompt)

- No direct trainer-student connection endpoint outside of checkout
 No student list view for trainers in CMS
 No real-time listener for connection status

Step 6: Surface to user before first question

Before asking the first idea-explorer question, show a summary:

📂 Context gathered from codebase:

Related files found: 7
Existing patterns: MVVM + Repository (iOS) / Firebase Auth + Firestore
Similar feature: Student enrollment at src/api/students/

Already exists:
  ✅ Student entity (src/types/student.ts) — has trainerId? field
  ✅ Trainer entity (src/types/trainer.ts)
  ✅ handleCheckoutComplete — creates trainer-student link after Stripe

Gaps detected:
  ❌ No direct connect API outside checkout flow
  ❌ No trainer CMS view of students

Injecting this context into spec generation...

Output location

.claude/feature-state/{slug}/context.md

This file is:

• Injected into idea-explorer as initial context (question framing)
• Injected into spec-writer as architectural context
• Referenced during PRD Validation to verify entity references