Skip to content

questio phase 1: implement questio_docs_collect MCP tool

Goal

Implement the questio_docs_collect MCP tool that generates docs/plan/ pages from questions.yml and milestones.yml.

Context

The questio spec (section 10 of docs/specs/research-orchestration/design.md) defines five auto-generated pages: - docs/plan/questions.md — question registry table - docs/plan/milestones.md — milestone tracker with evidence links - docs/plan/roadmap.md — mermaid dependency graph with status colors - docs/plan/evidence.md — per-question evidence index - docs/plan/index.md — landing page with overall progress

This follows the pipeio_docs_collect pattern. The tool reads YAML from plan/, scans docs/log/result/ for evidence notes, and generates markdown.

Prerequisite: Phase 0 tasks must be done (questions.yml + milestones.yml exist in pixecog).

Prompt

Implement the questio_docs_collect MCP tool in projio.

Step 1: Read the questio spec sections 4.2 and 10 at /storage2/arash/projects/projio/docs/specs/research-orchestration/design.md.

Step 2: Study the existing pipeio_docs_collect pattern: - Read /storage2/arash/projects/projio/src/projio/mcp/pipeio.py — find the pipeio_docs_collect tool registration - Read the corresponding implementation in pipeio to understand how docs generation works - Read /storage2/arash/projects/projio/src/projio/mcp/server.py to see how MCP modules are registered

Step 3: Create /storage2/arash/projects/projio/src/projio/mcp/questio.py with the questio_docs_collect tool:

The tool should: 1. Find plan/questions.yml and plan/milestones.yml in the project root (use PROJIO_ROOT env var) 2. Parse both YAML files 3. Scan docs/log/result/ for result notes and parse their frontmatter (question, milestone, confidence fields) 4. Generate five markdown files in docs/plan/: - questions.md — table with columns: ID, Question, Type, Status, Milestones (x/y), Evidence (count), Section (link) - milestones.md — tables grouped by related questions, columns: Milestone, Status, Pipeline, Depends on, Evidence (links to result notes) - roadmap.md — mermaid graph built from milestone dependencies, nodes colored by status (done=green, progress=yellow, pending=grey) - evidence.md — sections per question, each listing result notes with metric/value/confidence/date - index.md — summary line (x/y milestones, x/y questions sufficient) + links to other pages 5. Return list of generated file paths

Step 4: Register the tool in server.py — add questio module import and tool registration following the pattern of other modules.

Step 5: Test against pixecog: - Set PROJIO_ROOT=/storage2/arash/projects/pixecog - Run the tool and verify generated markdown is well-formed - Check that mermaid diagram renders correctly

Step 6: Commit: "Implement questio_docs_collect MCP tool"

Acceptance Criteria

  • [ ] src/projio/mcp/questio.py exists with questio_docs_collect tool
  • [ ] Tool registered in server.py
  • [ ] Generates all 5 docs/plan/ pages from YAML
  • [ ] Mermaid roadmap diagram has correct dependencies and status colors
  • [ ] Evidence index links to actual result notes
  • [ ] Tested against pixecog data
  • [ ] Committed

Result

(Filled in after execution)