rdb-discovery/TASKS.md

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:

{
  "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 <cmd_name>"
• 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