context-investigator

Context Investigator

Исследует контекст проекта чтобы task-decomposer мог делать качественную декомпозицию.

Когда применять

• Phase 1 каждого sprint cycle
• Запускается sprint-orchestrator'ом сразу после pre-flight

Что исследует

Чтение в этом порядке (later sources override earlier для conflicts):

1. HANDOFF.md (если есть)

Читает HANDOFF.md в корне проекта. Если есть:

• Recent activity - что было сделано недавно
• Open questions - незакрытые вопросы
• Important decisions - архитектурные/бизнес решения
• Next priorities - на что фокус

2. Project context brief (если есть)

Поиск по convention:

• docs/specs/_project-context/brief.md
• docs/_project-context/brief.md
• docs/PROJECT_CONTEXT.md
• PROJECT.md

Если найдено - извлекает:

• Domain (бизнес-предметная область)
• Stakeholders
• KPI и goals
• Доменные термины
• Technology stack (если упомянут)

3. Glossary (если есть)

Поиск:

• docs/glossary.md
• GLOSSARY.md
• docs/_project-context/glossary.md

Извлекает: domain terminology mapping (English ↔ project-specific term).

4. README.md

Корневой README. Извлекает:

• Project description
• Setup instructions (даёт hint о tech stack)
• Architecture overview (если есть)
• Contribution guidelines

5. Stack decisions / ADRs (если есть)

• docs/architecture/adr/*
• docs/adr/*
• docs/architecture/_stack-decisions.md

Извлекает: конкретные архитектурные решения с обоснованиями.

6. Project structure

find . -maxdepth 3 -type d -not -path '*/node_modules*' -not -path '*/.venv*' -not -path '*/.git*'

Извлекает:

• Top-level layout (src/, apps/, lib/, etc.)
• Module organization
• Test structure

7. Recent activity (git history)

git log --oneline -50
git log --pretty=format:"%h %an %s" --since="1 month ago" | head -100

Извлекает:

• What was being worked on recently
• Recent contributors
• Recent commit message patterns

8. Manifest files

• package.json → JS/TS deps, scripts, frameworks
• pyproject.toml / requirements.txt / Pipfile → Python deps
• go.mod → Go modules
• Cargo.toml → Rust crates

Извлекает: language stack, frameworks, dev tools.

Output

Создать .sprints/active/context-snapshot.md:

# Context Snapshot

**Generated**: {timestamp}
**Project root**: {path}

## Project identity

- **Name**: {detected from package.json/etc or directory name}
- **Type**: web-fullstack | web-frontend | web-backend | library | cli-tool | monorepo | other
- **Domain**: {detected from brief/glossary or "general purpose"}

## Tech stack

- **Languages**: {list with percentages}
- **Frameworks**: {detected per language}
- **Test runners**: {pytest, vitest, jest, go test, etc.}
- **Package managers**: {npm, pip, poetry, go mod, etc.}

## Domain knowledge

### Glossary (if available)

- **{Term1}**: {Definition}
- **{Term2}**: {Definition}

### Key entities (if mentioned in brief or models)

- {Entity1}: {description}
- {Entity2}: {description}

## Project structure

{simplified directory tree, depth 3}

## HANDOFF state

- **Last updated**: {timestamp from HANDOFF.md or "never"}
- **Recent activity**: {first paragraph of HANDOFF.md or "no HANDOFF.md found"}
- **Open questions**: {list or "none documented"}
- **Last decisions**: {list or "none documented"}

## Recent git activity

- **Last commit**: {hash, author, message}
- **Active areas** (most-changed files in last month): {top 5}
- **Recent work pattern**: {brief description}

## Notable patterns detected

- {Pattern 1, e.g., "Uses Django REST framework conventions"}
- {Pattern 2, e.g., "Test files in same directory as source (pytest convention)"}
- {Pattern 3, e.g., "Monorepo with apps/ and libs/ split"}

## Confidence assessment

How well do we understand this project?

- **High confidence** in: {areas where we have strong evidence}
- **Medium confidence** in: {areas based on inference}
- **Low confidence** in: {areas with insufficient info}

## Recommendations for task-decomposer

Based on this context:

1. {Specific suggestion based on stack and domain}
2. {Suggestion about testing approach common in this codebase}
3. {Suggestion about file naming/structure conventions to follow}

Failure mode

If insufficient information to understand domain:

В strict mode:

• В чат: "Cannot auto-detect domain context. Please provide briefly:
  • What is the business domain of this project?
  • Any specific terminology I should know?"
• Wait for user response, incorporate в context-snapshot

В lenient mode:

• Same prompt но не блокирует - может продолжать с "general purpose" assumption
• Помечает confidence = LOW в snapshot

В permissive mode:

• Continue with "unknown domain" assumption
• Confidence = LOW в snapshot
• task-decomposer применяет generic decomposition

Performance

• Should complete in <2 minutes даже для крупных проектов
• File reads ограничены (top 50 commits, top 5 directory levels, only key files)
• Don't read entire codebase - just metadata

Honesty

Context snapshot should reflect actual evidence, не assumptions:

• Если HANDOFF.md absent - явно "no HANDOFF.md found", не fabricate
• Если glossary empty - явно "no domain terminology found"
• Если recent commits unclear - "recent activity pattern not clear"

Это критично для task-decomposer чтобы знать what's solid evidence vs what's inferred.