# TASKS ## TASK-000 — Bootstrap RDB project standards Status: Done Goal: Add the project control files used by RDB agent workflows. Acceptance Criteria: - PROJECT_STATE.md exists - AGENT_HANDOFF.md exists - .rdb/project.json exists - context/repository-context.md exists - TEST_PLAN.md exists - RUN_LOG.md exists - README.md explains the structure ## TASK-001 — Implement rdb init Status: Done Goal: Create the command that initialises the standard RDB project structure. ## TASK-002 — Generate agent prompts Status: Done Goal: Add a command that generates a ready-to-paste implementation prompt for the next Todo task. Acceptance Criteria: - `rdb prompt` reads the next Todo task from TASKS.md - The prompt tells the agent to read README.md, TASKS.md, PROJECT_STATE.md, AGENT_HANDOFF.md, and context/agent-guidelines.md - The prompt says to implement one task only - The prompt includes the task title, status, goal, and acceptance criteria - The prompt includes validation instructions - The prompt includes reporting instructions - Add or update tests ## TASK-003 — Improve discovery workflow Status: Done Goal: Improve `rdb discover` so it records structured answers into the discovery ledger. Acceptance Criteria: - Ask the 10 core discovery questions - Record: - Question - Answer - Confidence - Follow-up needed - Linked decision - Linked task - Date - Append answers safely - Preserve existing discovery history - Add/update tests - Update RUN_LOG.md ## TASK-004 — Implement ask-more command Status: Done Goal: Add a command that finds weak answers and asks deeper follow-up questions. Acceptance Criteria: - command reads discovery-log.md - low-confidence answers are detected - follow-up answers are appended to discovery-log.md ## TASK-005 — Task lifecycle commands Status: Done Goal: Allow tasks to be managed from the CLI rather than manually editing TASKS.md. Acceptance Criteria: - `rdb start TASK-ID` - Marks task In Progress - `rdb complete TASK-ID` - Marks task Done - Updates PROJECT_STATE.md - Updates AGENT_HANDOFF.md - Updates RUN_LOG.md - Preserves task formatting - Add/update tests - Run python -m pytest ## TASK-006 — Agent execution guardrails Status: Done Goal: Detect agent stalls, repeated reads, long reasoning loops, and non-progressing execution. Acceptance Criteria: - `rdb guardrails` command exists ✓ - Detects repeated file reads via AGENT_HANDOFF.md analysis ✓ - Detects repeated command entries in RUN_LOG.md ✓ - Flags project files not modified in >48 hours ✓ - Flags missing test run records in RUN_LOG.md ✓ - Checks TASKS.md ↔ RUN_LOG.md consistency ✓ - Produces clear human-readable report with overall status ✓ - All existing tests still pass (33 → 51) ✓ - Guardrail-specific tests added (18 new tests) ✓ ## TASK-007 — Improve generated agent prompts Status: Done Goal: Make `rdb prompt` produce smaller, more direct prompts for Claude Code/local LLM agents. Acceptance Criteria: - Prompt includes exact known implementation gap when available - Prompt includes existing test command from CLAUDE.md - Prompt tells agent not to repeatedly reread unchanged files - Prompt tells agent to inspect first, then edit - Prompt limits scope to one small implementation step - Add/update tests ## TASK-012 — Telemetry foundation Status: Done Goal: Create a minimal telemetry system that can record structured agent activity for future guardrail and analysis features. Implementation Gap: The project currently infers agent behaviour from documentation, task files, and run logs. There is no structured event log showing what actions an agent actually performed during a session. Acceptance Criteria: - Create a telemetry module - Create `.rdb/session-log.jsonl` automatically when recording an event - Support recording events in JSONL format - Each event contains: - timestamp - event_type - target - details - Provide a simple public function for writing telemetry events - Add/update tests Example Event: ```json { "timestamp": "2026-06-02T12:00:00Z", "event_type": "command", "target": "rdb prompt", "details": {} } ``` Constraints: - Do not integrate telemetry into existing commands yet - Do not modify guardrails yet - Do not implement dashboards or reporting - Build the smallest useful telemetry foundation only Definition of Done: - Telemetry writer exists - JSONL file is created correctly - Events append correctly - Tests pass - Documentation updated if required ## TASK-013 — Record CLI command execution Status: Done Goal: Record rdb CLI command execution using the telemetry system. Implementation Gap: Telemetry storage exists but no command activity is recorded. Acceptance Criteria: - Record command execution events - Include command name - Include timestamp - Add/update tests Definition of Done: - All 10 CLI commands record a telemetry event on invocation - Events have event_type "command" and target "rdb " - Timestamps are present in UTC ISO format - New integration tests added to test_telemetry.py (4 new tests) - All 75 tests pass ## TASK-014 — Integrate telemetry with guardrails Status: Done Goal: Use structured telemetry data in guardrail analysis. Implementation Gap: Guardrails currently rely on heuristics and markdown files rather than actual activity records. Acceptance Criteria: - Read telemetry events ✓ - Detect repeated commands ✓ - Detect repeated reads when available ✓ - Fall back gracefully when telemetry is absent ✓ - Add/update tests ✓ Result: Two new guardrail checks added: - `check_repeated_commands_telemetry` — uses session-log.jsonl to detect repeated CLI commands (>3x) - `check_repeated_reads_telemetry` — uses session-log.jsonl to detect repeated file reads (>3x) Both integrate into `run_all_guardrails` alongside existing heuristic checks. When telemetry data is absent, both return `"ok"` with an informative fallback message instead of failing. ## TASK-015 — Re-centre project purpose Status: Done Goal: Clarify that rdb-discovery exists to help generate and maintain useful project context files for AI-assisted development. Implementation Gap: The project now has task, prompt, guardrail, and telemetry features, but the core product purpose needs to be made explicit again. Acceptance Criteria: - Update README.md with a clear project purpose - Explain the core workflow: - ask discovery questions - capture answers - generate context files - support agent implementation - Clarify that telemetry and guardrails support the workflow but are not the main product - Add/update tests only if required ## TASK-016 — Define standard context file templates Status: Done Goal: Define the standard context files that rdb-discovery should help generate. Implementation Gap: There is not yet a clear built-in definition of the context files the tool should produce. Acceptance Criteria: - Define templates for: - company-context.md - development-context.md - infrastructure-context.md - agent-guidelines.md - project-brief.md - architecture.md - Templates include headings and placeholder guidance - Keep templates simple markdown - Add/update tests ## TASK-017 — Support task roles in generated prompts Status: Done Goal: Allow tasks to define the agent role used by `rdb prompt`. Implementation Gap: Tasks can now include a `Role:` field, but `rdb prompt` still always generates prompts beginning with `You are an implementation agent.` Acceptance Criteria: - Parse optional `Role:` field from task markdown - If `Role:` exists, use it in the generated prompt opening - If `Role:` is missing, default to `Implementation Agent` - Add/update tests - Do not change task execution behaviour Definition of Done: - `Role: Architecture Agent` generates `You are an architecture agent.` - Tasks without a role still generate implementation prompts - Tests pass ## TASK-018 — Role-based context selection Status: Done Role: Implementation Agent Goal: Allow `rdb prompt` to select different context files based on task role. Implementation Gap: Tasks can now define a role, but every generated prompt still asks the agent to read the same set of files regardless of task type. Acceptance Criteria: - Architecture Agent receives architecture-focused context - Implementation Agent receives implementation-focused context - Documentation Agent receives documentation-focused context - If no role exists, use current default file list - Add/update tests Definition of Done: - Context files differ by role - Existing prompts remain backward compatible - Tests pass ## TASK-019 — Define discovery-to-context mappings Status: Done Role: Architecture Agent Goal: Define how discovery answers should be transformed into project context files. Implementation Gap: Discovery answers are collected and stored, but there is no documented mapping between discovery questions and the context files they should populate. Acceptance Criteria: - Every discovery question maps to one or more context files - Every discovery question maps to a specific section within those files - Mapping is documented in markdown - Mapping is understandable by future agents - No context generation implementation yet - Add/update tests if required Definition of Done: - Mapping document exists - 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 mappings Status: Done Role: Implementation Agent Goal: Generate context file content using the approved discovery-context-mapping.md document. Implementation Gap: Mappings now exist, but discovery answers are not yet transformed into context file content. Acceptance Criteria: - Read discovery-context-mapping.md ✓ - Read discovery-log.md ✓ - Populate mapped sections in context files ✓ - Create missing context files safely ✓ - Do not overwrite existing content ✓ - Skip low-confidence answers ✓ - Add/update tests ✓ Definition of Done: - Discovery answers appear in the correct context files ✓ - Existing content is preserved ✓ - Tests pass ✓ (114 tests, all passing) Result Created `src/rdb_discovery/generate_context.py` module with: - `CONTEXT_MAP`: Rules mapping each of the 10 discovery questions to target context files and sections (body-fill, table-row, or append-new-section strategies) - `generate_context_files(root, min_confidence)`: Main entry point that reads discovery answers, filters by confidence, applies mapping rules, and writes/updates context files safely - Three write strategies: TBD-replacement for empty sections, content-appending for existing body-text sections, table-row insertion for risks.md and assumptions.md, and new-section appending when headers don't exist yet Added `rdb generate` CLI command (accepts `--min-confidence` option). Fixed a parsing bug in `discovery.py`: escaped pipe characters (`\|`) in discovery answers were creating spurious extra columns during markdown table splitting — now handled with placeholder-based escaping. Added `tests/test_generate_context.py` with 15 tests: - Mapping completeness (all 10 questions, all target files) - Confidence filtering (Low → skipped, High/Medium → generated) - Body text filling (TBD replacement, existing content append) - Table row generation (risks.md and assumptions.md formats) - Content preservation verification - CLI command availability and error handling - Missing file creation safety - End-to-end integration flow ## TASK-021 — Context health report Status: Done Role: Implementation Agent Goal: Provide a single command that reports the health and completeness of project context. Implementation Gap: Context files can now be generated, but there is no way to assess whether sufficient context exists for effective AI-assisted development. Acceptance Criteria: - Add `rdb context-status` ✓ - Report expected context files ✓ - Report missing context files ✓ - Report sections still containing TBD placeholders ✓ - Report low-confidence discovery answers ✓ - Display an overall health score ✓ - Add/update tests ✓ (26 tests) Definition of Done: - Command runs successfully ✓ - Missing context is reported clearly ✓ - Health score is displayed ✓ - Tests pass ✓ (140 total, all passing) Result Created `src/rdb_discovery/context_status.py` module with: - `_expected_files()` — returns the 18 expected context file paths - `_check_expected_files()` — checks each file for existence and size - `_check_tbd_sections()` — scans context files for TBD/TDB placeholders (skips blank lines) - `_check_low_confidence()` — reads discovery-log.md for low-confidence answers - `compute_health_score()` — 0-100 score with weighted breakdown (45 pts file completeness, 30 pts no TBDs, 15 pts no low-conf, 10 pts discovery data) - `context_status()` — orchestrates all checks and returns structured report Added `rdb context-status` CLI command with: - Rich table of expected files with presence/absence indicators - TBD placeholder listing with file, section, and line number - Low-confidence discovery answer listing with ID and confidence level - Color-coded health score (green ≥ 70, yellow ≥ 40, red < 40) - Summary line showing counts Added `tests/test_context_status.py` with 26 tests across 4 classes: - TestExpectedFiles — file existence detection - TestTbdDetection — TBD/TDB placeholder scanning - TestLowConfidence — low-confidence answer detection - TestHealthScore — score computation and degradation - TestContextStatus — structured report verification - TestCLICommand — CLI registration, output, and edge cases - TestHealthScoreColor — score boundary validation All 140 tests pass. ## TASK-022 — Expand discovery coverage Status: Done Role: Architecture Agent Goal: Collect enough information to populate all standard context files. Implementation Gap: Several context files remain mostly placeholders because discovery questions do not collect the information required to populate them. Acceptance Criteria: - Review all context templates ✓ - Identify unmapped sections ✓ - Add additional discovery questions where required ✓ - Update discovery-to-context mapping ✓ - Add/update tests ✓ Definition of Done: - Every major template section has a discovery source ✓ - Discovery-to-context mapping updated ✓ - Tests pass ✓ (140, all passing) Result Added 4 new grouped discovery questions (Q-011 through Q-014) covering all major unmapped sections: | Question ID | Category | Target Sections | | ----------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- | | Q-011 | Organisation/project ownership | company-context.md Mission, project-brief.md Target Audience | | Q-012 | Technology stack and repository structure | development-context.md Tech Stack, Coding Standards; architecture.md Overview, Core Components | | Q-013 | Infrastructure/deployment/security | infrastructure-context.md Hosting, Environments, Monitoring & Alerting, Security | | Q-014 | Agent/developer workflow | agent-guidelines.md Purpose and Preferred Tools; repository-context.md Purpose and Contributing | Coverage expanded from 16 section targets (10 questions) to 28 section targets (14 questions). Files modified: - `src/rdb_discovery/templates.py` — Added 4 new questions to CORE_QUESTIONS - `src/rdb_discovery/generate_context.py` — Added Q-011 through Q-014 mappings; updated all_questions list in \_write_table_row - `context/discovery-context-mapping.md` — Added 4 new question entries, detailed mapping tables, and summary matrix rows - `tests/test_generate_context.py` — Updated question count assertions to use dynamic CORE_QUESTIONS - `tests/test_discovery_mapping.py` — Renamed test to match dynamic question count - `tests/test_discovery.py` — Updated assertion from exact 10 to >= 10 ## TASK-023 — Improve generated context quality Status: Done Role: Implementation Agent Goal: Improve the quality and usefulness of generated context files after `rdb generate`. Implementation Gap: `rdb generate` now writes discovery answers into some context files, but several useful context files remain mostly placeholders and some answers are mapped to weak or incorrect sections. Acceptance Criteria: - Populate `company-context.md` when discovery answers include users, product purpose, or stakeholders - Populate `agent-guidelines.md` when answers include tools, constraints, risks, or testing preferences - Populate `repository-context.md` when answers include project purpose, dependencies, or contribution/testing approach - Do not map testing answers into timeline/milestone sections - Fix `TDB` placeholder typos to `TBD` - Preserve existing non-placeholder content - Add/update regression tests using the current sample discovery-log data Definition of Done: - Running `rdb generate` on the sample discovery log produces useful content in more than just product/project brief files - Context files contain fewer irrelevant placeholders - Tests pass ## TASK-024 — Add objectivity and efficiency guidelines Status: Done Role: Documentation Agent Goal: Reduce token waste and unnecessary agreement in agent interactions. Implementation Gap: Agent guidance does not yet explicitly discourage praise, repeated context reading, task restatement, or unnecessary narrative output. Acceptance Criteria: - Update `context/agent-guidelines.md` - Add objectivity guidance - Add context-discipline guidance - Add communication-efficiency guidance - Add execution-efficiency guidance - Keep guidance concise and role-neutral - Add/update tests only if required Definition of Done: - `context/agent-guidelines.md` includes objectivity and efficiency guidance - Guidance helps reduce token usage without preventing useful technical reasoning - Existing workflow remains unchanged ## TASK-025 — Define discovery gap analysis model Status: Done Role: Architecture Agent Goal: Define how missing or weak project context should be detected and converted into targeted follow-up discovery questions. Acceptance Criteria: - Define gap detection rules - Define gap severity levels - Define question generation rules - Define question prioritisation rules - Define mapping between missing context sections and follow-up questions - Document the model - Define the follow-on implementation task - No implementation Definition of Done: - Gap analysis model documented - Follow-up question model documented - Example gap-to-question mappings included - TASK-026 implementation task defined Result Created `context/gap-analysis-model.md` (320 lines) as a planning artifact documenting: 1. **Gap detection rules** — 4 rule types (GAP-01 through GAP-04): TBD placeholders, unmapped sections, partial content, near-empty files 2. **Severity levels** — S1 (Critical), S2 (Important), S3 (Low) with assignment criteria per stage and mapping status 3. **Question generation rules** — 6 rules (QG-01 through QG-06): one-gap-per-question, answerable format, section reference, table-column specificity, skip-filled sections, owner-answer alignment 4. **Question prioritisation** — Ordered by severity → file completeness → dependency order → question scope 5. **Gap-to-question mapping table** — 40+ section-level mappings across all 16 template context files (excludes CLI-managed project-level files) 6. **End-to-end example flow** — Step-by-step walkthrough from detection through prioritisation to follow-up generation to regeneration 7. **Edge cases** — Partial sections, acceptable TBDs, new templates, multi-question sections, heading-only files 8. **TASK-026 implementation scope** — CLI command spec (`rdb gap`), module structure, test requirements (~45 tests across 6 categories) ## TASK-026 — Implement discovery gap analysis Status: Todo Role: Implementation Agent Goal: Implement the approved discovery gap analysis model. Acceptance Criteria: - Analyse generated context files - Detect missing sections - Generate follow-up questions - Link questions to missing context sections - Add/update tests ## TASK-027 — Context-driven follow-up questions Status: Todo Role: Implementation Agent Goal: Generate follow-up discovery questions based on previous answers. Implementation Gap: Discovery questions are currently static and do not adapt based on project-specific answers. Acceptance Criteria: - Follow-up questions are generated from discovery answers - Different answers produce different follow-up questions - Rules are deterministic and testable - Add/update tests Definition of Done: - Discovery flow becomes adaptive - Follow-up questions are linked to discovery answers - Tests pass ## TASK-028 — Improve discovery answer reliability UX Status: Todo Role: Architecture Agent Goal: Make answer reliability easier for users to understand during discovery. Implementation Gap: Users are asked to provide a confidence level, but confidence is an internal implementation concept and may not reflect how users think about the reliability of information. Acceptance Criteria: - Review confidence collection workflow - Define a more intuitive reliability model - Maintain compatibility with existing confidence filtering - Update discovery-to-context documentation - Add/update tests if required Definition of Done: - Reliability terminology is documented - Mapping to internal confidence levels is defined - Future implementation work is clearly specified ## TASK-029 — Capture AI tool targets Status: Todo Role: Architecture Agent Goal: Allow discovery to capture which AI development tools will consume generated project context. Implementation Gap: Generated context is currently tool-agnostic, but different tools require different guidance files and configuration formats. Acceptance Criteria: - Define supported tool categories: - Claude Code - Cline - Cursor - ChatGPT - GitHub Copilot - Local LLMs - Other - Add discovery question for AI tool usage - Update discovery-to-context mapping - Define which generated files are generic - Define which generated files are tool-specific - Do not implement tool-specific generation yet Definition of Done: - Tool model documented - Discovery captures tool preferences - Future generation requirements are defined ## TASK-040 — Generate Claude Code permission profile Status: Todo Role: Documentation Agent Goal: Create a recommended Claude Code permissions configuration for RDB workflows. Implementation Gap: Claude Code permission settings are not currently documented, resulting in unnecessary approval prompts and inconsistent behaviour between projects. Acceptance Criteria: - Define recommended safe commands for auto-approval - Define commands that should require approval - Document the profile in CLAUDE.md - Include rationale for each category Definition of Done: - Permission profile documented - CLAUDE.md updated ## TASK-050 — AI-assisted discovery questioning Status: Todo Goal: Use an LLM to propose the most valuable next discovery questions. Acceptance Criteria: - Review existing context - Review discovery history - Suggest follow-up questions - Keep human approval in the loop