report

Harness Report — Stakeholder Documentation

Generate clear, sourced reports for stakeholders. Aggregate from briefs, specs, prototypes, and codebase inspection.

Prerequisites

Check for .harness/kb/stack-profile.md. If missing, tell the user to run /harness:init first.

Context Loading

• .harness/kb/stack-profile.md — for high-level context
• Scan documents/shapings/ (or target_dir) for related briefs, specs, and design docs
• Load domain-relevant KB files based on report topic

Report Types

Type	Best for	Key outputs
Feature Landscape	What exists across the codebase for a domain	Capability inventory, gaps, diagrams
Feasibility Assessment	Can we do it? + What would it take? + Risks	Combines shape + ground findings, effort breakdown
Architecture Overview	System components and relationships	Data flow diagrams, component inventory, API endpoints
Progress Summary	Aggregate status of ongoing work	Status of all specs/briefs in target_dir

Process

Step 1: Determine Report Type and Scope

Ask if not clear:

• What type of report? (landscape / feasibility / architecture / progress)
• What domain or scope? (specific feature, entire system, recent work)
• Output format? (markdown in target_dir — default)

Step 2: Gather Data

From briefs/specs: Scan target_dir for recent artifacts and aggregate findings.

From codebase (READ-ONLY operations only):

• Database schema and relationships
• API endpoint listing
• UI component inventory
• Job/async system inventory
• Git history for recent changes (if relevant)

From KB files: Load domain-relevant KB files for context.

Step 3: Draft Report

Structure:

1. Executive Summary — 2-3 sentences with the key finding or recommendation
2. Scope — What this report covers and does not cover
3. Findings — Sourced findings with evidence:
   • Reference specific files, tables, components by name and path
   • Include Mermaid diagrams where they clarify relationships
   • Include data tables for structured information
4. Recommendations — Numbered, with rationale
5. Sources — List all files, KB entries, and codebase paths consulted

Step 4: Save

Save to {target_dir}/{date}-{topic}-report.md with frontmatter:

---
title: "{report title}"
type: report
date: {ISO date}
report-type: {landscape|feasibility|architecture|progress}
sources: [{list of referenced files}]
---

Also store via MCP: call harness_add_skillflow_step with skill_type: "report".

Guardrails

• Only READ-ONLY operations on the codebase — never modify, create, or delete
• Every finding must cite its source (file path, KB section, or codebase location)
• Mermaid diagrams should clarify, not decorate — only include when they add understanding
• Reports should be concise and scannable — use tables, bullet points, and headers
• Executive summary should be readable by non-technical stakeholders
• Recommendations should be actionable and specific