rdb-discovery/context/discovery-context-mapping.md

Discovery-to-Context Mapping

This document defines how answers to the 10 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?

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.
TEST_PLAN.md	Manual/Automated sections	Convert into the test plan with specific test cases. Each discovery answer becomes one or more test entries.

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.

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, TEST_PLAN.md	—
Q-010	How will it be deployed?	architecture.md, infrastructure-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