# Reporter Protocol

> Loaded by the run-parity-test-h entry skill to supply operating protocol and invariants for markdown validation report formatting in the parity-test-h pipeline. Not user-invocable.

- Skill: `gustavo-meilus/reporter-protocol-4` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gustavo-meilus/reporter-protocol-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gustavo-meilus/reporter-protocol-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: gustavo-meilus (https://skillmd.com/u/gustavo-meilus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gustavo-meilus/reporter-protocol-4

---


# Reporter — Operational Protocol

<overview>
The reporter step reads the reviewed findings produced by the reviewer step, formats a structured markdown validation report with separate sections for required-field violations, type mismatches, deprecated keys, and dismissed findings, and writes the report to `{ROOT}/output/parity-test-h-validation-report.md`. It is the final step of the parity-test-h Sequential pipeline (Pattern 1) on Tier 2 (Cursor/Windsurf/Cline), executing inline in the entry skill's session. The quality bar is: the output must be a readable markdown file whose confirmed findings are clearly separated by category and whose dismissed findings are documented with their dismissal rationale.
</overview>

## Protocol

<protocol>

### 1. DISCOVER

1. Read inputs from the orchestrator execution context:
   - `reviewed_findings_path`: path to `reviewed-findings.json` written by the reviewer step.
   - `output_path`: path where the final validation report must be written (always `{ROOT}/output/parity-test-h-validation-report.md`).
   - `state_path`: path to `pipeline-state.json` for status updates.
   - `run_id`: current run identifier.
   - `root`: resolved scope root.
2. Verify `reviewed_findings_path` exists and is a readable file. If not: update `pipeline-state.json` phases[2].status = "blocked"; emit `BLOCKED` with message: "Reviewed findings not found at `{reviewed_findings_path}`. The reviewer step may have failed."
3. Parse the reviewed findings JSON. If JSON is malformed: update `pipeline-state.json` phases[2].status = "blocked"; emit `BLOCKED` with message: "Reviewed findings at `{reviewed_findings_path}` are not valid JSON. Re-run the reviewer step."

### 2. PROCESS

**Step 2.1 — Partition findings by category and status:**

From `reviewed-findings.json`, partition the findings into four groups:
1. `confirmed_required_fields`: findings where `category = "required_field"` and `review_status = "confirmed"`.
2. `confirmed_type_mismatches`: findings where `category = "type_mismatch"` and `review_status = "confirmed"`.
3. `confirmed_deprecated_keys`: findings where `category = "deprecated_key"` and `review_status = "confirmed"`.
4. `dismissed`: all findings where `review_status = "dismissed"`, regardless of category.

**Step 2.2 — Render the markdown report:**

Format the markdown report using the following template:

```markdown
# YAML Validation Report — parity-test-h

**Source file**: {source_path}
**Reviewed at**: {reviewed_at}
**Run ID**: {run_id}
**Total findings**: {total_findings} ({confirmed} confirmed, {dismissed} dismissed)

---

## Summary

| Category | Confirmed | Dismissed |
|---|---|---|
| Required field violations | {n} | {n} |
| Type mismatches | {n} | {n} |
| Deprecated keys | {n} | {n} |
| **Total** | **{confirmed}** | **{dismissed}** |

---

## Required Field Violations

{If no confirmed required-field findings: "_No required field violations confirmed._"}

{For each confirmed required-field finding:}
### {id}: {key}

- **Severity**: Error
- **Message**: {message}

---

## Type Mismatches

{If no confirmed type-mismatch findings: "_No type mismatches confirmed._"}

{For each confirmed type-mismatch finding:}
### {id}: {key}

- **Severity**: Error
- **Expected type**: `{expected_type}`
- **Actual type**: `{actual_type}`
- **Actual value**: `{actual_value}`
- **Message**: {message}

---

## Deprecated Keys

{If no confirmed deprecated-key findings: "_No deprecated keys confirmed._"}

{For each confirmed deprecated-key finding:}
### {id}: {key}

- **Severity**: Warning
- **Message**: {message}

---

## Dismissed Findings (False Positives)

{If no dismissed findings: "_No findings were dismissed._"}

{For each dismissed finding:}
### {id}: {key} ({category})

- **Original severity**: {severity}
- **Original message**: {message}
- **Dismissal rationale**: {review_note}

---

_Report generated by parity-test-h pipeline on Tier 2 (Cursor/Windsurf/Cline). Reviewer isolation is convention-only; review was performed within the same agent session as validation._
```

**Step 2.3 — Handle zero-confirmed-findings edge case:**

If `confirmed` = 0 (all findings dismissed, or zero findings from validator): the report still renders with all sections showing the "no findings" placeholder text. Emit `DONE_WITH_CONCERNS` with message: "Report written with zero confirmed findings. Either the YAML is fully valid or all findings were dismissed as false positives."

### 3. DELIVER

1. Create the `{root}/output/` directory if it does not exist.
2. Write the rendered markdown report to `output_path` using the Write tool.
3. Update `pipeline-state.json`:
   - Set `phases[2].status` = `"completed"` (or `"completed_with_concerns"` if zero confirmed findings).
   - Set `phases[2].outputs` = `[output_path]`.
   - Set `phases[2].outputs_summary` = `{ "confirmed_findings": N, "dismissed_findings": N }`.
   - Set top-level `status` = `"completed"` (or `"completed_with_concerns"` as appropriate).
   - Set `completed_at` = current ISO-8601 timestamp.
4. Emit terminal status:
   - `DONE` — report written successfully with at least one confirmed finding.
   - `DONE_WITH_CONCERNS` — report written but contained zero confirmed findings (note reason).
   - `BLOCKED` — reviewed-findings file missing or malformed; output not written.

</protocol>

<invariants>
- ALWAYS write the output to exactly `{ROOT}/output/parity-test-h-validation-report.md` — never a different path.
- ALWAYS include all four report sections (required fields, type mismatches, deprecated keys, dismissed) even when a section has zero entries.
- ALWAYS include the footer note about convention-only reviewer isolation in the report.
- NEVER write partial output — if rendering fails mid-way, do not write the file; emit BLOCKED.
- NEVER hardcode platform paths — use only the `root` value supplied in the execution context.
- ALWAYS update `pipeline-state.json` phases[2] and top-level status after writing.
- NEVER suppress dismissed findings from the report — they must appear in the Dismissed Findings section with their rationale.
- Emit exactly one terminal status: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED.
</invariants>