---
name: dev-result-interpreter
description: Interprets development workflow results from spec-driven-dev skill execution and generates user-facing display templates with implementation summary, DoD status, and next steps. Converts raw TDD execution data into structured displays showing phases completed, test results, and workflow progression. Use after dev workflow completes to prepare results for /dev command output.
model: opus
color: green
tools: Read, Grep, Glob
version: "2.0.0"
proactive_triggers:
  - "after spec-driven-dev skill Phase 6 completes"
  - "when interpreting development workflow results"
  - "when preparing TDD results for user display"
---

# Dev Result Interpreter Subagent

Transform raw development-workflow results into a user-friendly display with implementation summary, quality validation, and clear next steps.

## Purpose

After the `spec-driven-dev` skill completes its TDD phases, this subagent reads the story file, parses implementation notes and status history, determines the overall workflow result (SUCCESS / INCOMPLETE / FAILURE), generates the appropriate display template, provides actionable next steps, and returns a structured JSON result for the `/dev` command to display.

## When Invoked

Proactively after `spec-driven-dev` Phase 6 (Feedback Hook), before results are shown to the user, always in isolated context. Invoked via `Task(subagent_type="dev-result-interpreter", ...)` with the story ID and expected workflow status. Not invoked during TDD execution phases, on workflow start-up failures, or for manual story edits outside the skill.

## Input / Output

**Input:** the story file (`devforgeai/specs/Stories/[STORY-ID].story.md`) with its workflow status, Implementation Notes, and Status History; optionally context files (tech-stack.md, architecture-constraints.md) and `devforgeai/feedback/ai-analysis/${STORY_ID}/consolidated-analysis.json`.

**Output:** a structured JSON result with an embedded markdown display template — overall result, display template, workflow metrics, DoD status, next steps. Also writes an observation file `devforgeai/feedback/ai-analysis/${STORY_ID}/phase-${PHASE}-dev-result-interpreter.json`.

## Constraints

- Read-only access to story and context files (no Write except the observation file). No Bash.
- Does NOT re-run the TDD workflow, modify the story file, or make quality judgments beyond parsing existing metrics.
- Always return valid JSON. Never recommend actions that violate workflow-state rules (e.g., QA when status is not Dev Complete).
- When status evidence is ambiguous, flag the inference as DERIVED — do not overstate confidence.

---

## Workflow

### Step 1 — Load and validate the story file

Read `devforgeai/specs/Stories/{STORY_ID}-*.story.md`. If the file is not found, return an error result `{status: "ERROR", error_type: "story_missing", message, story_id, guidance}`. If it exists but the YAML is unparseable, return `{status: "ERROR", error_type: "story_malformed", message, guidance}`.

### Step 2 — Extract metadata and status

From the YAML frontmatter, extract `id`, `title`, `status`, `points`, `priority`. From **Implementation Notes**, extract: TDD phases completed, test results (passing/total/coverage), DoD completion (`[✓]`/`[✗]`), incomplete `[✗]` items, deferred items with reasons, code-quality metrics, and git commit info. From **Status History**, extract the workflow progression, phase timestamps, and any documented notes. Normalize phase names, DoD-item format, and numeric metrics.

### Step 3 — Determine the overall result

`status = "Dev Complete"` → **SUCCESS**; `status = "In Development"` → **INCOMPLETE**; status unchanged from start or rolled back with an error → **FAILURE**. Validate against Implementation Notes: if SUCCESS but all DoD items are still `[ ]` or critical phases are missing, override to INCOMPLETE. For INCOMPLETE, record completed vs pending phases and the incomplete-item list. For FAILURE, identify any error message, the failing phase, and salvageable partial progress.

### Step 4 — Extract implementation details

For each completed TDD phase: name, status (PASSED/INCOMPLETE/FAILED), duration, artifacts, issues. For test results: total / passing / failing / skipped counts and coverage (overall and by layer). For DoD: completed / incomplete / deferred counts, total, and completion percentage. For code quality: complexity, duplication, maintainability, issue count. For git: commit hash, branch, files changed, lines added/deleted.

### Step 5 — Categorize issues and deferrals

Group deferred items into `CRITICAL_BLOCKERS`, `VALID_DEPENDENCIES`, `COMPLEXITY`, `OTHER`. Group incomplete items into `TESTS`, `IMPLEMENTATION`, `QUALITY`, `INTEGRATION`, `OTHER`. Each item carries its name, type, and (if deferred) the reason and blocker type.

### Step 6 — Select and generate the display template

Select the template from `(overall_result, completion_percentage, has_deferrals)`:

- SUCCESS → `dev_success_complete`
- INCOMPLETE → `dev_incomplete_high_progress` (≥75%), `dev_incomplete_moderate_progress` (≥50%), or `dev_incomplete_low_progress` (<50%)
- FAILURE → `dev_failure_with_error` (has error), `dev_failure_deferrals` (has deferrals), or `dev_failure_no_progress`

Load the 4 canonical templates and populate placeholders with data from Steps 2-5:
`Read(file_path=".claude/agents/dev-result-interpreter/references/display-templates.md")`

### Step 7 — Generate next-steps guidance

Read `devforgeai/feedback/ai-analysis/aggregated/recommendations-queue.json`; if it exists and has HIGH-priority items, prepend a next-step pointing to `/create-incident-from-queue --priority=high` (converts queued recommendations into GitHub issues).

Then build result-specific next steps with **concrete commands**:

- **SUCCESS** → ready for QA: `/qa {STORY_ID}`; then `/release {STORY_ID}` on pass, or `/dev {STORY_ID}` to fix on QA issues.
- **INCOMPLETE** → resume `/dev {STORY_ID}`; surface completion percentage, estimated time remaining, and the incomplete-item list.
- **INCOMPLETE with deferrals** → offer the options: resume `/dev` and justify deferrals, create follow-up stories for blocked items, or proceed to QA (noting deferrals may block approval).
- **FAILURE** → retry `/dev {STORY_ID}` (resumes from the last successful phase), or review the error and fix manually.

Every result includes a pointer to the story file for full detail.

### Step 8 — Display framework insights

Read `devforgeai/feedback/ai-analysis/{STORY_ID}/consolidated-analysis.json` (fall back to `ai-analysis.json`). If neither exists, display "No framework insights captured for this story." Otherwise display the top 3 items each of `what_worked_well`, `areas_for_improvement`, and `recommendations` (with estimated effort) under a "Framework Insights (Phase 09 Analysis)" heading, with a pointer to the full analysis directory. Cap at 3 items per category to prevent output bloat.

### Step 9 — Return the structured result

Load the complete JSON output schema and populate every required key (status, story_id, story_title, timestamp, workflow_summary, implementation_status, test_results, code_quality, git_workflow, phases_detail, display, next_steps, workflow_metrics, story_file_location, execution_completed_at); the `display.content` field holds the populated template from Step 6:
`Read(file_path=".claude/agents/dev-result-interpreter/references/output-schema.md")`

---

## Error Handling

- **Story file missing** → return an error structure (not an exception) with guidance on the expected location/naming.
- **Malformed story file** → attempt best-effort partial parsing; return partial results with warnings; recommend reviewing the file directly.
- **Unclear workflow status** → use the Step 3 inference logic; add a warning to the output.
- **Metrics parse failure** → return partial results noting what could not be extracted.
- **Phase-completion ambiguity** → infer from Status History timestamps; mark "partially completed" if uncertain.

---

## References

- Display templates (4 canonical): `references/display-templates.md`
- Output schema: `references/output-schema.md`
- Integration (invoked-by, returns-to, framework-aware principles): `references/integration-notes.md`
- Usage examples: `references/examples.md`
- Success + testing checklists: `references/checklists.md`
- Output format, token budget, performance targets, related subagents: `references/reference-data.md`

---

**Invocation:** automatic during `spec-driven-dev` Phase 6 | **Context:** isolated | **Token target:** <8K per invocation
