185 lines
8.9 KiB
Markdown
185 lines
8.9 KiB
Markdown
# 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
|