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 — Add context completeness report

Status: Todo

Role: Implementation Agent

Goal:

Report which expected context files exist and which sections still need information.

Implementation Gap:

There is no way to determine whether a project has sufficient context for effective AI-assisted development.

Acceptance Criteria:

• Add a context status/check command
• Report present context files
• Report missing context files
• Report obvious placeholder sections still needing completion
• Add/update tests

Definition of Done:

• Context report command exists
• Missing context is reported clearly
• Tests pass

TASK-022 — 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