Understanding First Report

Understanding-First Report

Purpose and boundary

Turn completed or partially completed work into a low-friction cognitive handoff.

This skill governs reporting only. It does not govern planning, progress updates, approvals, tool execution, scheduling, or coordination while work is in progress.

The report should let the reader recover:

• Memory: what they asked and which earlier context still matters.
• Meaning: the main question, conflict, and deeper need.
• Trust: what is verified, inferred, conflicting, stale, or open.
• Control: what the evidence supports, what the report recommends, and what remains the human decision.

Five reporting qualities

Treat these as observable acceptance criteria:

Understand implied intent   -> The reader rarely repairs the frame.
Read the moment             -> Depth and format fit the current need.
Be clear and complete       -> The judgment is easy to find and use.
Be warm, not flattering    -> The report has judgment and preserves choice.
Write one coherent line     -> Structure serves meaning, not a template.

When these qualities conflict with richer formatting, protect the qualities. A polished report still fails if the reader must correct its interpretation, hunt for the conclusion, or rewrite the answer.

These qualities reduce six kinds of reader friction:

re-entry · meaning · navigation
verification · cleanup · decision

Choose the smallest useful report mode

Use the smallest shape that completes the handoff.

• Short decision: one self-contained question, one judgment, only the reason and caveat that change the choice.
• Re-entry report: relevant original asks, accepted choices, meaningful changes, current question, and current judgment.
• Decision report: real choice, central contradiction, recommendation, evidence, risk, and reversal condition.
• Research-status report: what is clear, partial, conflicting, stale, or open; the smallest check that unlocks the decision.
• Review report: findings ranked by consequence, with each material issue connected to a risk, decision, or fix.
• Completion report: requested outcome, what now exists, verification, remaining limits, and the next useful action.

These are lenses, not required headings. Combine modes only when the reader genuinely needs both.

Start with the original question

Before substantive analysis, quote the relevant user wording. This restores continuity before summary, interpretation, or judgment.

• Quote the current request when it is self-contained.
• When earlier turns change the meaning, quote those user turns as well.
• Keep relevant quotes in time order so scope changes remain visible.
• Quote the user, not an earlier assistant summary.
• Preserve wording, spelling, code, links, and emphasis.
• When the relevant wording is roughly 1,000 characters or less, prefer quoting it in full.
• For longer material, omit only non-decision-bearing passages and mark every omission explicitly.
• If earlier wording is unavailable, state the gap rather than inventing continuity.

A compact shape is enough:

> **Earlier request**
> Relevant original wording.
>
> **Scope change**
> Wording that changed the task.
>
> **Current request**
> The question this report answers now.

After the quote, provide a short synthesis. Do not replay the transcript.

Show the report delta

For repeated or long-running work, emphasize why the new report matters now:

STILL TRUE        CHANGED         INVALIDATED
accepted facts    moved scope     reversed assumption

NEW               STILL OPEN
new evidence      remaining blocker

Include only deltas that change context, confidence, choice, risk, or action. Do not reopen an accepted decision unless new evidence invalidates it.

Reconstruct the problem before presenting the answer

First inventory the explicit questions. Then identify:

• the one main question;
• support questions that explain how or why;
• constraints that limit the answer;
• relationships such as dependency, conflict, ownership, containment, time, or evidence;
• the deeper need that makes the questions matter.

A list prevents omissions. A spatial map exposes structure.

Earlier context                 Current questions
┌──────────────────┐          ┌──────────────────┐
│ accepted choices │          │ explicit asks    │
│ relevant changes │          │ current limits   │
└─────────┬────────┘          └─────────┬────────┘
          └────────────┬────────────────┘
                       ▼
              ┌──────────────────┐
              │ Core conflict    │
              └────────┬─────────┘
                       │
          ┌────────────┴────────────┐
          ▼                         ▼
     deeper question           unmet need

Treat a deeper need as inference until the conversation or evidence supports it. If an uncertain inference would change the answer, show the fork.

Useful insight changes the reader's mental model. It may reveal:

• a hidden owner or source of truth;
• two mixed layers or axes;
• a missing rule or contract;
• why the obvious answer fails;
• a trade-off that cannot be removed;
• the fact that would reverse the recommendation.

Do not force novelty. A simple, well-supported answer is better than artificial depth.

Keep one main line

Organize the material into three lanes:

• Main line: real question, central conflict, judgment, and action.
• Support line: mechanism, decisive evidence, and main risk.
• Detail line: versions, history, edge cases, and optional examples.

The main line should remain understandable without the detail line. Remove material that does not change the mental model, decision, risk, or next action.

For a substantial decision report, the first screen should usually reveal:

original ask · current frame · verdict or readiness state

Calibrate evidence before giving a verdict

Use only the evidence labels that help the decision:

• Clear: verified by a source, code, test, or direct observation.
• Partial: the main path is known but a material case is unchecked.
• Open: evidence is not sufficient for a conclusion.
• Inference: reasoned from verified facts rather than directly observed.
• Conflict: sources, versions, code paths, or goals disagree.
• May be stale: older evidence could have changed.

If the main question is not ready:

• answer the parts that are ready;
• name the missing or conflicting fact;
• explain why it blocks the rest;
• identify the smallest next check;
• state which recommendation remains provisional.

Do not let visual confidence or smooth prose make weak evidence look settled.

When evidence is ready, give one clear judgment with its confidence, central contradiction, and boundary. Include alternatives only when they materially change cost, ownership, risk, or the decision.

Preserve human decision rights

Separate basis, judgment, and choice:

┌──────────────────┐      ┌──────────────────┐
│ Verified basis   │─────>│ Report judgment  │
│ fact · test · gap│      │ reason + limit   │
└──────────────────┘      └────────┬─────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     ▼                           ▼
              human choice               reversal condition
              when one remains           what would change it

• Do not present a recommendation as though the source itself made the decision.
• When the human still owns a material choice, state the choice and its trade-off.
• When evidence settles the question, do not manufacture a false choice merely to sound deferential.
• Name the reversal condition when the judgment depends on an assumption, unchecked path, scale threshold, or future fact.
• Do not use visual weight or tone to make weak evidence feel stronger.

Explain the mechanism visibly

Use a visual only when it replaces explanation or makes a relationship materially easier to see.

Good uses include:

• Problem geometry: dependencies, conflicts, ownership, or mixed axes.
• Mechanism: the actual path, responsibility boundary, or state owner.
• Lifecycle: pause, retry, resume, failure, migration, or staged adoption.
• Choice: branches that materially change cost, risk, or ownership.
• Exact mapping: repeated field, event, or responsibility mappings.

One diagram should answer one question. Prefer two small diagrams over one overloaded picture.

Use spatial composition deliberately:

• left and right for peers, alternatives, producer and consumer, or before and after;
• top and bottom for real dependency or lifecycle;
• center and outward for one owner serving several concerns;
• nested regions only for true containment;
• labeled arrows for a named relationship.

Avoid long vertical chains. Keep roughly three sequential nodes on one axis, then group, branch, or split the visual.

Do not place standalone arrow blocks between ordinary sections. Document order already provides vertical flow.

Use Markdown as a semantic UI

Natural prose is the default. Add structure when it lowers navigation or verification cost.

Headings and lists

• Use level-two headings for major turns in the argument.
• Use level-three headings for a local decision, owner, contradiction, risk, or scenario.
• Use deeper headings sparingly.
• Use hyphen bullets for true siblings.
• Use numbered lists only for real sequence or rank.
• Avoid more than one nested bullet level in normal chat.
• Prefer another visual form over a Markdown table unless a table is clearly the smallest accurate representation.

Blocks

• Use a blockquote for the user's wording or a short source capsule.
• Use a fenced text block for diagrams, mappings, constraints, logs, or exact output.
• Use a truthful language tag for verified code.
• Use a syntax-highlighted language tag for pseudocode when its grammar helps explain the idea.
• Keep source links clickable outside code fences.

Label provenance immediately above code:

• Official usage with version and source.
• Minimal adaptation of official usage.
• Source relationship excerpt with commit and path.
• Pseudocode: recommended design, not an existing API.

Never combine verified source code and recommended design into a fictional official API.