Skip to content

questio phase 2: implement questio_status and questio_gap MCP tools

Goal

Implement the two query MCP tools that let agents orient and assess evidence gaps.

Context

The questio spec (section 6.1 of docs/specs/research-orchestration/design.md) defines three MCP tools. questio_docs_collect is implemented in phase 1. This task adds: - questio_status — overview of research state (questions with status, evidence counts, milestone %) - questio_gap — evidence gap analysis per question (unmet milestones, missing pipelines, confidence levels)

Both tools parse plan/questions.yml, plan/milestones.yml, and scan docs/log/result/ for evidence notes. They should be added to the existing src/projio/mcp/questio.py module.

Prerequisite: Phase 1 (questio.py module exists).

Prompt

Add questio_status and questio_gap tools to the existing questio MCP module.

Step 1: Read the questio spec section 6.1 at /storage2/arash/projects/projio/docs/specs/research-orchestration/design.md.

Step 2: Read the existing /storage2/arash/projects/projio/src/projio/mcp/questio.py to understand the module structure and any shared YAML parsing logic from phase 1.

Step 3: Implement questio_status:

Args: - question_id (optional, str, default "") — if provided, return details for that question only

Returns dict with: - questions: list of question summaries, each with: - id, text, type, status - milestone_progress: "x/y complete" - evidence_count: number of linked result notes - blockers: list of blocking milestone IDs (dependencies not met) - overall: total questions, milestone %, evidence count

Logic: 1. Load questions.yml and milestones.yml 2. For each question, count completed milestones (from milestones.yml status) 3. Scan docs/log/result/ for notes with matching question IDs in frontmatter 4. Identify blockers: milestones whose depends_on includes incomplete milestones

Step 4: Implement questio_gap:

Args: - question_id (required, str) — which question to analyze

Returns dict with: - question: the question text and status - milestones: list of milestones for this question, each with: - id, description, status - blocked_by: list of incomplete dependency milestone IDs - pipelines: which pipeio flows are needed - evidence: list of linked result notes (from scanning docs/log/result/) - evidence_confidence: highest confidence level among linked results - gaps: summary of what's missing: - unmet_milestones: IDs of incomplete milestones - blocked_milestones: IDs blocked by dependencies - actionable_milestones: IDs that are unblocked and can be worked on now - missing_evidence: milestones with no linked result notes - recommendation: text summary of highest-impact next action

Logic: 1. Load both YAML files 2. Build dependency graph for the question's milestones 3. Resolve which are blocked vs actionable 4. Scan result notes for evidence 5. Compute gaps and generate recommendation

Step 5: Factor out shared logic (YAML loading, result note scanning) into helper functions within the module. The YAML loading and note scanning from questio_docs_collect should be reusable.

Step 6: Test both tools against pixecog: - questio_status() should return all 7 questions with current states - questio_status(question_id="H1") should return H1 details - questio_gap(question_id="H3") should show dependency chain and actionable items

Step 7: Commit: "Add questio_status and questio_gap MCP tools"

Acceptance Criteria

  • [ ] questio_status returns structured overview of all questions
  • [ ] questio_status with question_id filters to single question
  • [ ] questio_gap resolves dependency graph correctly
  • [ ] questio_gap identifies actionable vs blocked milestones
  • [ ] Shared YAML/note parsing logic factored out
  • [ ] Tested against pixecog data
  • [ ] Committed

Result

(Filled in after execution)