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

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