# Discovery-to-Context Mapping

This document defines how answers to the 14 core discovery questions should be transformed into project context files.

## Reference: Core Discovery Questions

| ID | Question |
|---|---|
| Q-001 | What problem are we solving? |
| Q-002 | Who is the user? |
| Q-003 | What does success look like? |
| Q-004 | What is the minimum useful version? |
| Q-005 | What data do we need? |
| Q-006 | What systems must it connect to? |
| Q-007 | What are the risks? |
| Q-008 | What must not happen? |
| Q-009 | How will we test it? |
| Q-010 | How will it be deployed? |
| Q-011 | Who owns and directs the project, and what are its organisational goals? |
| Q-012 | What is the technology stack, repository structure, and architecture approach? |
| Q-013 | Where is it hosted, which environments exist, and what are the security requirements? |
| Q-014 | What agent and developer workflow tools, constraints, and guidelines apply? |

## Reference: Target Context Files

All paths are relative to the project root.

| File | Purpose |
|---|---|
| `context/discovery-log.md` | Source of discovery answers — not a target, but the input to mapping |
| `context/product-brief.md` | Product vision, users, success criteria, MVP scope |
| `context/project-brief.md` | Detailed project brief with problem statement and timeline |
| `context/architecture.md` | System design, components, data flow, integrations, deployment |
| `context/decisions.md` | Architecture and design decision records (ADR-style table) |
| `context/risks.md` | Risk register with impact and mitigation columns |
| `context/assumptions.md` | Project assumptions with confidence and validation status |
| `context/open-questions.md` | Open questions needing further investigation |
| `context/development-context.md` | Tech stack, coding standards, build/test instructions |
| `context/infrastructure-context.md` | Hosting, environments, CI/CD, monitoring, security |
| `context/agent-guidelines.md` | Agent operating rules for this project |
| `context/company-context.md` | Company goals and constraints that shape the project |
| `context/repository-context.md` | Repository structure, workflow, and contributing info |
| `TEST_PLAN.md` | Manual and automated test plan |

## Mapping: Question → Context Files + Sections

### Q-001 — What problem are we solving?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/product-brief.md` | `## Problem` | The raw answer fills in the product problem statement. If the answer is vague, split it into customer pain and desired outcome. |
| `context/project-brief.md` | `## Problem Statement` | Restate in project-specific terms. Include scope boundaries if mentioned. |
| `context/company-context.md` | (append to Goals) | Link back to company-level goals if the answer references them. |

### Q-002 — Who is the user?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/product-brief.md` | `## Users` | Record user personas, roles, or segments. Use bullet points for each distinct user type. |
| `context/company-context.md` | `## Customers / Users` | If the answer identifies external customers rather than internal users, append to this section. |
| `context/development-context.md` | `## IDEs and Editors` | Note any tooling constraints specific to the target users (if they are developers). |

### Q-003 — What does success look like?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/product-brief.md` | `## Success Criteria` | Record measurable success criteria as a numbered or bulleted list. Each criterion should be verifiable. |
| `context/project-brief.md` | `## Success Metrics` | Restate with specific measurement approach (e.g., user count, latency threshold, coverage %). |

### Q-004 — What is the minimum useful version?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/product-brief.md` | `## Minimum Useful Version` | List MVP features as bullet points. Each feature should be independently valuable. |
| `context/project-brief.md` | `## Key Features (MVP)` | Expand with brief descriptions for each MVP feature. |
| `TASKS.md` | New TASK entries | Consider generating initial task rows from MVP features. |

### Q-005 — What data do we need?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/architecture.md` | `## Data Flow` | Describe data entities, storage locations, and movement between components. |
| `context/development-context.md` | `## Dependencies` | Record database platforms, storage services, or data stores required. |
| `context/infrastructure-context.md` | `## Environments` | Note any data requirements per environment (dev/staging/prod data parity). |

### Q-006 — What systems must it connect to?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/architecture.md` | `## External Integrations` | List each external system with its role (API, database, auth provider, etc.). |
| `context/infrastructure-context.md` | Append as section | If the integration requires infrastructure changes, document there. |
| `context/decisions.md` | New row | If integration choices involved trade-offs, record as a decision. |

### Q-007 — What are the risks?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/risks.md` | Data rows | Each risk becomes a row with columns: ID, Risk Description, Impact (High/Med/Low), Mitigation, Status. Assign sequential IDs like RISK-001. |
| `context/open-questions.md` | New rows | Any unresolved aspects of a risk become open questions. |

### Q-008 — What must not happen?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/assumptions.md` | Data rows | Constraints that are actually assumptions about what won't be done. Record confidence and validation need. |
| `context/decisions.md` | New row | If a "must not" is the result of an active decision (e.g., "no third-party auth"), record as a decision with reasoning. |
| `context/open-questions.md` | New rows | Any constraint that needs clarification becomes an open question. |

### Q-009 — How will we test it?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/development-context.md` | `## Build & Test` | Document test framework, test execution commands, and local setup steps. |
| `context/agent-guidelines.md` | `## Testing Preferences` (append) | Add a new section describing how tests should be written, run, and verified. Do **not** map testing answers into Timeline / Milestones sections in other files. |

### Q-010 — How will it be deployed?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/architecture.md` | `## Deployment Architecture` | Describe the deployment layout, scaling strategy, and process. |
| `context/infrastructure-context.md` | `## CI / CD Pipeline`, `## Hosting`, `## Environments` | Fill in hosting platform, environment details, and pipeline steps from the discovery answer. |

### Q-011 — Who owns and directs the project, and what are its organisational goals?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/company-context.md` | `## Mission` | Record the organisation's core mission, vision, or strategic goals that relate to this project. If no company-level mission exists, record the team's purpose. |
| `context/company-context.md` | `## Products & Services` (append) | Add a new section describing the company's products and services if the answer includes them. |
| `context/project-brief.md` | `## Target Audience` | Restate in project-specific terms — who will use or benefit from the final product? |

### Q-012 — What is the technology stack, repository structure, and architecture approach?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/development-context.md` | `## Tech Stack` | Extract languages, frameworks, libraries, tooling, and build/test tools. Record each as a distinct item. |
| `context/development-context.md` | `## Coding Standards` | Note any style conventions, naming patterns, linters, formatters, or agreed-upon patterns. If none exist, note "TBD". |
| `context/repository-context.md` | `## Dependencies` (append) | Add a new section describing project dependencies if not yet documented. |
| `context/architecture.md` | `## Overview` | Record high-level design principles, architectural patterns (e.g., monolith, microservices), and key design decisions. |
| `context/architecture.md` | `## Core Components` | List the main modules, services, or packages and their responsibilities. Use bullet points for each component. |

### Q-013 — Where is it hosted, which environments exist, and what are the security requirements?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/infrastructure-context.md` | `## Hosting` | Record hosting platform (cloud provider, on-prem, container orchestration, etc.). |
| `context/infrastructure-context.md` | `## Environments` | List all environments (dev/staging/prod), their purpose, and data management approach. |
| `context/infrastructure-context.md` | `## Monitoring & Alerting` | Document monitoring tools, alerting channels, and observability requirements. |
| `context/infrastructure-context.md` | `## Security` | Record authentication models, data protection requirements, compliance needs, and access control policies. |

### Q-014 — What agent and developer workflow tools, constraints, and guidelines apply?

Maps to:

| Context File | Section | Guidance |
|---|---|---|
| `context/agent-guidelines.md` | `## Purpose` | Record why agents need specific context for this project (constraints, conventions, expectations). |
| `context/agent-guidelines.md` | `## Preferred Tools` | List recommended editors, debuggers, testing frameworks, CLI tools, and automation tools. |
| `context/repository-context.md` | `## Purpose` | Record the project's overall purpose, scope boundaries, and what it is / is not responsible for. |
| `context/repository-context.md` | `## Contributing` | Document contribution process, branch strategy, code review requirements, and testing expectations for contributors. |

## Summary: Question-to-File Matrix

This matrix provides a quick-reference view of all mappings. "Primary" means the answer should go there first; "Secondary" means it may also be updated if relevant.

| Q-ID | Question | Primary Context Files | Secondary Context Files |
|---|---|---|---|
| Q-001 | What problem are we solving? | product-brief.md, project-brief.md | company-context.md |
| Q-002 | Who is the user? | product-brief.md, company-context.md | development-context.md |
| Q-003 | What does success look like? | product-brief.md, project-brief.md | — |
| Q-004 | Minimum useful version? | product-brief.md, project-brief.md | TASKS.md |
| Q-005 | What data do we need? | architecture.md, development-context.md | infrastructure-context.md |
| Q-006 | Systems to connect to? | architecture.md, infrastructure-context.md | decisions.md |
| Q-007 | What are the risks? | risks.md, open-questions.md | — |
| Q-008 | What must not happen? | assumptions.md, decisions.md | open-questions.md |
| Q-009 | How will we test it? | development-context.md, agent-guidelines.md | — |
| Q-010 | How will it be deployed? | architecture.md, infrastructure-context.md | — |
| Q-011 | Who owns and directs the project? What are its organisational goals? | company-context.md, project-brief.md | — |
| Q-012 | What is the technology stack, repository structure, architecture approach? | development-context.md, repository-context.md, architecture.md | — |
| Q-013 | Where is it hosted, which environments exist, and what are the security requirements? | infrastructure-context.md | — |
| Q-014 | What agent and developer workflow tools, constraints, and guidelines apply? | agent-guidelines.md, repository-context.md | — |

## Implementation Notes for Future Work

This document is a planning artifact. No code generation has been implemented yet.

### What future implementation should do

1. **Read** discovery-log.md (via `read_discovery_answers` in `discovery.py`)
2. **Classify** each answer by its question ID
3. **Transform** the answer text according to this mapping's section guidance
4. **Write** or update target context files, creating rows in tables where applicable
5. **Preserve** existing content — never overwrite sections without explicit user intent
6. **Record** what was generated so the user can review

### Constraints for future implementation

- Only process answers with High or Medium confidence
- Skip Low confidence answers (these should be handled by `ask-more` first)
- Use template format from `templates.py` as the base for context files
- Add new sections only if a discovery answer introduces entirely new content areas
- Log each mapping action to `.rdb/session-log.jsonl` for traceability

### Test requirements for future implementation

When code is eventually written, tests should verify:

- Each question ID maps to exactly the files listed in this document
- Empty/placeholder sections are populated correctly
- Existing file content is preserved (not overwritten)
- The matrix above passes programmatic validation against the mapping data