feat(task-019): define discovery-to-context mappings
This commit is contained in:
@@ -41,3 +41,8 @@
|
||||
{"timestamp": "2026-06-02T16:57:29.853052+00:00", "event_type": "command", "target": "rdb prompt", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:05:41.754949+00:00", "event_type": "command", "target": "rdb status", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:07:48.597850+00:00", "event_type": "command", "target": "rdb status", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:10:43.959746+00:00", "event_type": "command", "target": "rdb status", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:10:48.601943+00:00", "event_type": "command", "target": "rdb next", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:10:57.679687+00:00", "event_type": "command", "target": "rdb prompt", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:22:38.052771+00:00", "event_type": "command", "target": "rdb status", "details": {}}
|
||||
{"timestamp": "2026-06-02T17:35:19.867986+00:00", "event_type": "command", "target": "rdb status", "details": {}}
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ Current Stage: BUILDING
|
||||
Previous Stage: BOOTSTRAP_READY
|
||||
Next Stage: REVIEW_READY
|
||||
|
||||
Current Task: TASK-015
|
||||
Current Task: TASK-019
|
||||
Active Branch: main
|
||||
|
||||
Last Updated: 2026-06-02
|
||||
|
||||
@@ -337,7 +337,7 @@ Definition of Done:
|
||||
|
||||
## TASK-019 — Define discovery-to-context mappings
|
||||
|
||||
Status: Todo
|
||||
Status: Done
|
||||
|
||||
Role: Architecture Agent
|
||||
|
||||
@@ -364,6 +364,29 @@ Definition of Done:
|
||||
- Mapping covers all discovery questions
|
||||
- Future implementation work is clearly defined
|
||||
|
||||
Result
|
||||
|
||||
Created `context/discovery-context-mapping.md` which documents:
|
||||
|
||||
- Reference table of all 10 core discovery questions (Q-001 through Q-010)
|
||||
- Reference table of all target context files and their purpose
|
||||
- Detailed mapping for each question to primary and secondary context files with specific section guidance
|
||||
- Summary question-to-file matrix for quick reference
|
||||
- Implementation notes defining how future code should read discovery answers and populate context files
|
||||
- Constraints for future implementation (preserve existing content, skip low-confidence answers)
|
||||
- Test requirements for when code is eventually written
|
||||
|
||||
Added `tests/test_discovery_mapping.py` with 6 tests validating:
|
||||
|
||||
- Mapping file existence
|
||||
- All 10 core questions are present
|
||||
- Table-format documentation section exists
|
||||
- Summary matrix section exists
|
||||
- Future implementation notes exist (and clarify no code has been implemented yet)
|
||||
- All context files from templates.py are referenced in the mapping
|
||||
|
||||
No context generation implementation was added — this task is a planning artifact only.
|
||||
|
||||
## TASK-020 — Generate context files from discovery answers
|
||||
|
||||
Status: Todo
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
# 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
|
||||
@@ -0,0 +1,103 @@
|
||||
"""Tests for the discovery-to-context mapping document."""
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
# Path to the mapping document (relative to project root)
|
||||
MAPPING_FILE = "context/discovery-context-mapping.md"
|
||||
|
||||
|
||||
def _get_project_root() -> Path:
|
||||
"""Return the project root directory.
|
||||
|
||||
Walk up from this file's location to find the repo root.
|
||||
"""
|
||||
# Start from tests/ and walk up
|
||||
current = Path(__file__).resolve().parent.parent
|
||||
# Look for pyproject.toml or .git as markers
|
||||
while current != current.parent:
|
||||
if (current / "pyproject.toml").exists() or (current / ".git").exists():
|
||||
return current
|
||||
current = current.parent
|
||||
return Path.cwd()
|
||||
|
||||
|
||||
def test_mapping_file_exists() -> None:
|
||||
"""The discovery-to-context mapping file must exist."""
|
||||
root = _get_project_root()
|
||||
mapping_path = root / MAPPING_FILE
|
||||
assert mapping_path.exists(), f"Mapping file missing: {mapping_path}"
|
||||
|
||||
|
||||
def test_mapping_contains_all_10_questions() -> None:
|
||||
"""Every core discovery question must appear in the mapping."""
|
||||
from rdb_discovery.templates import CORE_QUESTIONS
|
||||
|
||||
root = _get_project_root()
|
||||
mapping_path = root / MAPPING_FILE
|
||||
content = mapping_path.read_text(encoding="utf-8")
|
||||
|
||||
for question in CORE_QUESTIONS:
|
||||
assert question in content, f"Question not mapped: {question}"
|
||||
|
||||
|
||||
def test_mapping_documentation_contains_table_format() -> None:
|
||||
"""The mapping must be documented in a table format (machine-readable)."""
|
||||
root = _get_project_root()
|
||||
mapping_path = root / MAPPING_FILE
|
||||
content = mapping_path.read_text(encoding="utf-8")
|
||||
|
||||
# Accept both the exact header and any variant that contains the key phrase
|
||||
has_section = ("Mapping: Question" in content or "Question → Context" in content)
|
||||
assert has_section, (
|
||||
"Missing 'Mapping: Question -> Context Files + Sections' section header"
|
||||
)
|
||||
|
||||
|
||||
def test_mapping_contains_summary_matrix() -> None:
|
||||
"""A summary question-to-file matrix table must exist."""
|
||||
root = _get_project_root()
|
||||
mapping_path = root / MAPPING_FILE
|
||||
content = mapping_path.read_text(encoding="utf-8")
|
||||
|
||||
assert "Question-to-File Matrix" in content, (
|
||||
"Missing 'Question-to-File Matrix' summary section"
|
||||
)
|
||||
|
||||
|
||||
def test_mapping_contains_future_implementation_notes() -> None:
|
||||
"""The mapping must define future implementation guidance."""
|
||||
root = _get_project_root()
|
||||
mapping_path = root / MAPPING_FILE
|
||||
content = mapping_path.read_text(encoding="utf-8")
|
||||
|
||||
assert "## Implementation Notes" in content or "## What future implementation should do" in content, (
|
||||
"Missing 'Implementation Notes' section"
|
||||
)
|
||||
# Verify it clearly states no code has been implemented yet
|
||||
assert "No code generation has been implemented" in content, (
|
||||
"Must clarify that mapping is a planning artifact with no code yet"
|
||||
)
|
||||
|
||||
|
||||
def test_mapping_covers_all_context_files() -> None:
|
||||
"""Every context file listed in templates.py must appear in the mapping."""
|
||||
from rdb_discovery.templates import CONTEXT_FILES
|
||||
|
||||
# Filter out control files (TASKS.md, PROJECT_STATE.md, etc.) and keep context files
|
||||
context_paths = {p for p in CONTEXT_FILES if p.startswith("context/")}
|
||||
|
||||
root = _get_project_root()
|
||||
mapping_path = root / MAPPING_FILE
|
||||
content = mapping_path.read_text(encoding="utf-8")
|
||||
|
||||
# Extract file paths from the mapping's Reference section
|
||||
found_files = set()
|
||||
for line in content.splitlines():
|
||||
for cp in context_paths:
|
||||
if f"`{cp}`" in line or cp in line:
|
||||
found_files.add(cp)
|
||||
|
||||
for cp in context_paths:
|
||||
assert any(cp in fp for fp in found_files), (
|
||||
f"Context file not referenced in mapping: {cp}"
|
||||
)
|
||||
Reference in New Issue
Block a user