Write Report

Write Report (Analysis Quality Review) — Review-Only Multi-Mode Grader

This is a protocol skill. It grades reader-facing deliverables and ghost-deck storylines. It does NOT edit them. Each invocation runs a single mode and returns a structured response. The calling skill — which has the substantive context that produced the document — writes the spec itself (using a template this skill provides) and applies fixes itself (using references/fix-patterns.md), then re-invokes this skill to verify the fixes landed.

Input convention. Reader-facing deliverables are typically HTML (combined reports with prose + charts/diagrams inline) at standard+ strictness. Markdown is acceptable for working drafts at low strictness. The rubrics and reviewers grade content (argument structure, prose readability) regardless of file format — HTML chrome is ignored, prose and section structure are what's graded. Machine artifacts (YAML datasets, JSON, machine-readable manifests) should NOT be reviewed — they are audit substrate, not reader-facing.

The skill is built on four agents and one mechanism:

• spec mode (no agent): returns the framework-matched authoring template path. File lookup only.
• Pre-flight (review modes only): artifact-loader (runs once per review audit, builds load_bearing_index.yaml)
• spec-judge mode: spec-judge agent — grades the filled-in authoring spec against the declared structural_framework
• review pass: 1: argument-structure-reviewer — grades document structure against the declared structural_framework
• review pass: 2: readability-reviewer — grades document readability (framework-independent — applies to any prose document)
• review pass: 3: readability-reviewer (humanization mode) — grades the document against the humanize specs (zero em-dashes, no AI tells, human texture present) after the caller has run the humanizer skill on it

Humanization is mandatory for reader-facing deliverables — with one scope carve-out. A document that passes structure and readability can still read as machine-written — clean but generic, em-dash-riddled, contrastive-negation tics, no human texture. For any doc_type in {brief, memo, deck, decision-record} at strictness ≥ standard, the end-to-end flow REQUIRES a humanize stage. Scope rule (owner decision, 2026-06-10): Pass 3 applies when the deliverable is human-read prose in the author's voice (memo, letter, post, executive report). It does NOT apply to agent-read, repo-resident documentation — docs whose primary consumer is an agent (or a team's agents) and that live inside a product/code repo with an established house voice (e.g. a product repo's docs/). There, match the repo's existing register instead; within-repo voice consistency beats memo-style consistency. Passes 1–2 still run. For the in-scope case: after Pass 2 clears, the calling skill runs the humanizer skill on the document (the edit), then Pass 3 grades that the humanize specs hold. This matters most for client-facing deliverables produced under the owner's name, where the standing rule is no em-dashes, the owner's voice. write-report still never edits — the humanizer skill performs the edit; write-report Pass 3 verifies it landed. Companion-skill dependency: Pass 3 assumes a humanizer editing skill on the caller's side. Any de-AI editing pass that satisfies references/rubric-humanization.md works; if no humanizer skill is installed, the Phase A priority greps inline in that rubric are the minimum pattern source.

Structural frameworks — pick one per document

Analytical documents don't all use the same structural skeleton. The skill grades against ONE primary framework per document, declared by the caller via structural_framework. Frameworks are not composable; pick the one whose dominant frame matches the document's intent. (Nested Minto-style checks fire inside rumelt-kernel and issue-tree where they apply — handled by the rubric, not by composing frameworks.)

| Framework | Fits this kind of document | Core structure | |---|---|---| | minto-pyramid | Recommendation brief, executive memo, partner deck | Governing observation → MECE supporting reasons → evidence (with SCQA opening) | | rumelt-kernel | Strategy document with explicit recommendation | Diagnosis → Guiding Policy → Coherent Actions (Minto checks fire nested) | | issue-tree | Problem-solving / hypothesis-testing analysis | Root question → MECE sub-questions → analysis under each | | scqa-only | Short communication / one-page message | Situation → Complication → Question → Answer | | adr | Decision record | Context → Decision → Consequences | | concept-page | Wiki / glossary / definitional doc | Definition → Properties → Relationships → Examples | | descriptive | Diagnostic / state-of-X report (no recommendation) | Phenomenon → Mechanisms → Implications (no apex governing-observation requirement) |

If the caller omits structural_framework, the skill infers a default from doc_type per references/framework-selection-guide.md. The inference is a soft default — callers should override it when their document's intent doesn't match the default (e.g., a doc_type: brief that is descriptive-not-recommendation should be tagged structural_framework: descriptive).

The recommended end-to-end caller sequence at standard+ strictness:

1. spec        → caller fills in template using subject context
2. spec-judge  → loop until PASS or max_spec_iterations (3)
3. write       → caller generates document using approved spec
4. review p:1  → loop until PASS
5. review p:2  → loop until PASS
6. humanize    → caller runs the `humanizer` skill on the document (the edit)
7. review p:3  → loop until PASS (verifies the humanize specs hold)

Stages 1-2 are the ghost-deck discipline (storyline before content). Stages 4-5 are post-hoc grading of the realized document. Stage 6 humanizes; stage 7 verifies. Each loop's fix step happens in the calling skill, not here.

Passes gate in sequence: Pass 1 (structure) gates Pass 2 (readability) gates Pass 3 (humanization). Humanization runs last because humanizing broken structure or unreadable prose produces polished noise — the same reason readability follows structure.

Why review-only

Analytical briefs carry cross-reference codes (SECRET-02, M1-DTC, CP-4), evidence tags ([V], [C]), framework citations (Phase 4.5), and cited numeric claims. The natural fixer of an analytical brief is the skill that generated it — it has the supporting artifacts in working memory, owns the cross-references, and can update brief + dataset coherently. Routing fixes through a separate fixer agent forced us to reinvent that context through a manifest scaffold, which was awkward and error-prone. Now: this skill grades rigorously and hands the calling skill a precise diagnosis it can act on. See references/load-bearing-architecture.md.

When to run

• An upstream analytical skill (reimagine-industry, analyze-industry, build-company-model, stress-test, build-brand, marketing-plan, /quarterly, /decide) has produced a long-form output and wants it verified before handoff.
• A user explicitly requests "quality review", "structure check", "readability audit" on a file.
• A document is about to be handed to a senior reader (partner, sponsor, investor).

Do NOT run on:

• Short chat replies (.md

**`mode: spec-judge`** and **`mode: review`** return the same five-line block:

PASS: spec-judge | 1 | 2 VERDICT: PASS | FAIL | BLOCKED | ESCALATE VIOLATIONREPORTPATH: FIXPATTERNSPATH: .claude/skills/write-report/references/fix-patterns.md AUDIT_DIR:

(For `spec-judge`, the `PASS` field reads `spec-judge` rather than `1` or `2` — it identifies which mode was just graded.) The `VERDICT` is the single verdict for the pass that was just run; the caller separately tracks whether earlier stages have already cleared.

## Orchestration

The orchestrator branches on `mode`. The three branches share the same five-line return contract (except `spec` which returns a single template path line).

### `mode: spec` — return authoring template

SPEC ORCHESTRATION (no pre-flight, no model call):

• Validate inputs: doc_type is set; mode is spec
• If structural_framework is supplied: use it directly

Else: infer from doc_type per references/framework-selection-guide.md

• If doc_type is daily-note: refuse — spec mode does not apply

(return TEMPLATE_PATH: BLOCKED — see Escalation cases)

• If structuralframework is concept-page and doctype is brief/memo/deck: warn but proceed

(caller has chosen non-default; that's allowed)

• Resolve to references/authoring-templates/.md
• Return single line: TEMPLATE_PATH:

No audit dir is created. No artifact-loader runs. The calling skill consumes the framework-specific template, fills it in using its subject context, writes the filled-in spec to a path of its choosing, and either ships the spec to `spec-judge` or proceeds without judgment (low-strictness only).

### `mode: spec-judge` — grade the filled-in spec

SPEC-JUDGE PRE-FLIGHT (first invocation only):

• Validate calling-contract inputs: specpath, doctype, intentsummary, supportingartifacts, template_path
• If audit_dir not supplied: create tasks/write-report/-/
• Snapshot the spec to /00-spec-original.md (first invocation only)
• NO artifact-loader (the spec has no codes-in-prose yet; cross-references are checked lightly inside the judge)

SPEC-JUDGE PASS (single invocation):

• If iteration > maxspeciterations (3): return VERDICT: ESCALATE
• Invoke spec-judge agent with the manifest + spec + template + previous_violations (if re-invocation)
• Judge returns verdict + structured report with preservationnote + suggestedfix_shape on each violation
• Orchestrator returns five-line block

CALLER LOOP (outside this skill):

• Caller reads report + fix-patterns.md (spec-stage fixes section)
• Caller revises the spec using its subject context
• Caller re-invokes spec-judge with the SAME auditdir, the revised spec, and previousviolations
• Loop until VERDICT = PASS or VERDICT = ESCALATE
• On PASS: caller proceeds to write the document; the spec-judge auditdir is RETAINED for traceability but the review modes create their own auditdir

### `mode: review` — grade the realized document

REVIEW PRE-FLIGHT (first invocation only):

• Validate calling-contract inputs
• If audit_dir not supplied: create tasks/write-report/-/
• Snapshot the input file to /00-original.md (first invocation only)
• If audit_dir was supplied (re-invocation): skip snapshot; index already exists
• Run artifact-loader → produces /loadbearingindex.yaml (first invocation only)

REVIEW PASS (single pass per invocation):

• If pass == 1: invoke argument-structure-reviewer
• If pass == 2: invoke readability-reviewer (only valid if Pass 1 has previously returned PASS for this audit_dir)
• If pass == 3: invoke readability-reviewer in humanization mode (only valid if Pass 2 has previously returned PASS for this audit_dir)
• Reviewer returns structured violation report (with preservationnote + suggestedfix_shape on load-bearing violations)
• Orchestrator returns five-line block to caller

CALLER LOOP (outside this skill):

• Caller reads violation report + fix-patterns.md
• Caller applies targeted Edit calls to the document, updating supporting artifacts as needed
• Caller re-invokes this skill with the SAME auditdir and previousviolations
• Reviewer grades whether fixes landed
• Loop until VERDICT = PASS (or caller bails)
• Then caller invokes Pass 2 against the same audit_dir, same loop pattern
• After Pass 2 PASS: caller runs the humanizer skill on the document (the edit), then invokes Pass 3

against the same auditdir. Pass 3's fix step IS re-running the humanizer on the flagged regions. Mandatory for doctype in {brief, memo, deck, decision-record} at strictness ≥ standard; optional at low.

### Recommended end-to-end caller flow (standard+ strictness)

1. caller → spec(doctype=brief) → TEMPLATEPATH
2. caller fills template using its subject context → writes filled-in spec
3. caller → spec-judge(spec_path, manifest, iter=1) → ITERATE | PASS

if ITERATE: caller revises spec, re-invokes (iter=2,3) → PASS or ESCALATE

1. caller writes the document using the approved spec
2. caller → review(document_path, pass=1, manifest) → ITERATE | PASS

loop until PASS

1. caller → review(document_path, pass=2) → ITERATE | PASS

loop until PASS

1. caller runs humanizer skill on the document → document edited in place
2. caller → review(document_path, pass=3) → ITERATE | PASS

loop until PASS (each ITERATE = re-run humanizer on flagged regions)

Stages 1-3 are the ghost-deck phase. Stages 4-6 are the post-hoc realization grading. Stages 7-8 are the humanization stage — mandatory for reader-facing deliverables (`brief`/`memo`/`deck`/`decision-record`) at standard+, where a document that is structurally and readably clean can still read as machine-written. Doing the spec phase is what saves 60-70% of iteration tokens vs post-hoc review alone — most structural failures (broken D1 governing observation, MECE-overlap, Rumelt goal-not-strategy) get caught at the 2-3K-token spec stage rather than at the 50-100K-token document stage.

## Pre-flight (applies to `mode: spec-judge` and `mode: review`; `mode: spec` skips pre-flight)

1. Verify the input file exists and is readable (`document_path` for review modes; `spec_path` for spec-judge).
2. Verify the file is text (markdown, plain text) — refuse binaries.
3. Verify required agent files exist:
   - `.claude/skills/write-report/agents/storyline-judge.md` (for `mode: spec-judge` — agent type is `storyline-judge`, mode name is `spec-judge`)
   - `.claude/agents/storyline-judge.md` (project-level registration pointer — required so Task tool can resolve subagent_type="storyline-judge")
   - `.claude/agents/artifact-loader.md` (registration pointer)
   - `.claude/agents/argument-structure-reviewer.md` (registration pointer)
   - `.claude/agents/readability-reviewer.md` (registration pointer)
   - `.claude/skills/write-report/agents/artifact-loader.md` (for `mode: review`)
   - `.claude/skills/write-report/agents/argument-structure-reviewer.md` (for `mode: review, pass: 1`)
   - `.claude/skills/write-report/agents/readability-reviewer.md` (for `mode: review, pass: 2`)
4. Validate the manifest per the strictness × doc_type matrix in the calling contract. BLOCK if required and missing.
5. Resolve `doc_type` and `strictness` against `references/applicability-matrix.md` to determine which dimensions fire. For `mode: spec-judge`, BLOCK if `doc_type` is `wiki` or `daily-note` (those types skip ghost-deck review by design).
6. If `audit_dir` not supplied: create it and snapshot the input file (`00-original.md` for review modes; `00-spec-original.md` for spec-judge).
7. For `mode: review` only — if `audit_dir` not supplied: invoke `artifact-loader` with the manifest. It produces `/load_bearing_index.yaml`. Both review passes read this index. If the loader returns BLOCKED, surface to caller and exit. Spec-judge does NOT run artifact-loader.

If `doc_type` is `daily-note` or `chat-reply` at `strictness: low`, write a one-line note to the audit dir, set verdict to `SKIPPED`, and exit. Do not over-review trivial documents.

## Spec-Judge Pass

iterationnumber = supplied iteration (default 1; cap 3) reportpath = "/spec-iter-report.md"

if iteration_number > 3: return VERDICT: ESCALATE (spec hasn't converged after 3 rounds — consult human)

Task(subagenttype="storyline-judge", prompt= doctype: structuralframework: strictness: iteration: reportpath: i

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Agent-Engineer-Master
• Source: Agent-Engineer-Master/skill-engineer
• License: MIT

Install and usage instructions live in the source repository linked above.