# Reporting Skill

> Specialized knowledge and step-by-step guidance for generating high-quality reports (Executive, Technical, or Complete). Use this skill when asked to create investigation reports with worked examples.

- Skill: `tankygranny05/reporting-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/reporting-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/reporting-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tankygranny05 (https://skillmd.com/u/tankygranny05)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tankygranny05/reporting-skill

---

<!-- [Edited by Claude: 2a51fb4e-1a96-4d2f-a1e1-d5bb1e208b1f] -->

# Reporting Skill

**Description**: specialized knowledge and step-by-step guidance for generating high-quality reports (Executive, Technical, or Complete).

## The Hard Example (Case Study)

**Agent Identity**: Codex (Session `019bff81-afd4-74f0-8dcf-2090fa59cb9d`, Suffix `52814`)
**Task**: Observability port audit for `claude-code-2.1.20` (Missing turn boundary events).

### 1. Technical Rigor (The "Before")
*Very dense, good technical rigor, but hard for non-technical stakeholders to digest.*

**Goal**
- In `2.1.20-obs`, restore emission of `claude.stop` + `claude.turn_end` when stop hooks finish.
- Emit **only** when the stopping agent is the **main** agent (session SID), never for subagents.

**Where Things Stand (2.1.20-obs)**
- Helpers already exist near the top of ` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js`:
  - `__cc_isMainAgent()`, `__cc_shouldEmitMainStopHook()`, `__cc_emitMainStopHookAndTurnEnd()` (`cli.js:270-312` area)
- But there are **no call sites** for `__cc_emitMainStopHookAndTurnEnd()` (only the definition), so `claude.stop` / `claude.turn_end` never get emitted.
- The “Anthropic stop hooks” system is present and runs via the Stop/SubagentStop hook machinery (e.g. hook input builder at ` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js:458185`), and the stop-hook runner is around ` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js:456240`.

---

## Implementation Plan

### 1) Make “main-agent-only” gating strict (centralized)
Edit `__cc_shouldEmitMainStopHook()` in ` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js` (near the bootstrap helpers, ~`cli.js:270-290`).

Current behavior can allow emission if a `"Stop"` hook event is observed, even if `agentId` is not the main agent. Tighten it:

- Always suppress when `agentId` is present and not main.
- Also suppress when we only saw `SubagentStop` (no `Stop`), since that implies a subagent stop hook ran.

Suggested logic (shape; adapt to minified style):

```js
function __cc_shouldEmitMainStopHook(agentId, sawStopHookEvent=!1, sawSubagentStopHookEvent=!1) {
  if (agentId && !__cc_isMainAgent(agentId)) return !1;          // hard main-only rule
  if (sawSubagentStopHookEvent && !sawStopHookEvent) return !1;  // subagent stop hook => no emit
  return !0;
}
```

This guarantees: even if subagent code somehow reports `"Stop"`, you still won’t emit unless `agentId` is main (or missing).

### 2) Wire stop/turn_end emission into the stop-hook runner
In the stop-hook runner function around ` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js:456240`, port the call-site pattern from `2.1.15` (where it exists at ` /Users/sotola/swe/claude-code-2.1.15/cli.js:401530`, `:401554`, `:401580`).

#### 2a) Track which hook event type was observed
Add local flags at the top of the function:

- `let __cc_seenStopHook = !1;`
- `let __cc_seenSubagentStopHook = !1;`

Then, inside the attachment handling block where it already checks:

`x.hookEvent === "Stop" || x.hookEvent === "SubagentStop"`

add:

```js
if (x.hookEvent === "Stop") __cc_seenStopHook = !0;
else if (x.hookEvent === "SubagentStop") __cc_seenSubagentStopHook = !0;
```

This gives you reliable signals to pass into `__cc_emitMainStopHookAndTurnEnd(...)`.

#### 2b) Emit on the 3 terminal outcomes (mirroring 2.1.15 behavior)
Add `try { __cc_emitMainStopHookAndTurnEnd(...) } catch {}` in these exact control-flow points:

1) **Abort/cancel path**
- In the branch:
  - `if (H.abortController.signal.aborted) { ... return; }`
  - located in the loop at ~` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js:456313`
- Add before the `yield kjA(...); return;`:

```js
try {
  __cc_emitMainStopHookAndTurnEnd(
    H.agentId,
    "stop_hook_cancelled",
    __cc_seenStopHook,
    __cc_seenSubagentStopHook
  );
} catch {}
```

2) **Prevent-continuation path**
- Right before the existing `if (T) return;` (T is preventContinuation) at ~`cli.js:456356`
- Replace with:

```js
if (T) {
  try {
    __cc_emitMainStopHookAndTurnEnd(
      H.agentId,
      "stop_hook_prevented_continuation",
      __cc_seenStopHook,
      __cc_seenSubagentStopHook
    );
  } catch {}
  return;
}
```

3) **Normal completion path**
- At the end, where it currently does:
  - `if (D.length > 0) yield* Qf(...);`
  - else falls off without emitting anything
- Wrap it like 2.1.15 does:

```js
if (D.length > 0) {
  yield* Qf(...);
} else {
  try {
    __cc_emitMainStopHookAndTurnEnd(
      H.agentId,
      "stop_hook_completed",
      __cc_seenStopHook,
      __cc_seenSubagentStopHook
    );
  } catch {}
}
```

Important: keep the “D.length > 0 => yield* Qf” behavior unchanged (don’t emit stop/turn_end in that branch unless you confirm 2.1.15’s logic was wrong; mirroring it minimizes risk).

### 3) Ensure the call sites compile and are discoverable
After wiring, `rg -n "__cc_emitMainStopHookAndTurnEnd\\("` on ` /Users/sotola/swe/claude-code-2.1.20-obs/cli.js` should show **multiple hits** (definition + new call sites).

---

## Testing Guide

### A) Syntax + wiring sanity
Run:

```bash
cd /Users/sotola/swe/claude-code-2.1.20-obs && \
  node --check cli.js && \
  rg -n "__cc_emitMainStopHookAndTurnEnd\\(" cli.js
```

Pass criteria:
- `node --check` exits 0
- `rg` shows call sites (not just the function definition)

### B) Functional: confirm `claude.stop` + `claude.turn_end` appear (main agent)
Run a single prompt in an isolated log dir:

```bash
cd /Users/sotola/swe/claude-code-2.1.20-obs && \
  rm -rf /tmp/stop-test-cb9d && \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  node cli.js --log-dir /tmp/stop-test-cb9d -p "hello"
```

Then count events:

```bash
python -c 'import json,collections; p="/tmp/stop-test-cb9d/sse_lines.jsonl"; c=collections.Counter(); \
[ c.__setitem__(json.loads(l)["event"], c[json.loads(l)["event"]]+1) for l in open(p) ]; \
print("stop", c["claude.stop"], "turn_end", c["claude.turn_end"]); print(c.most_common(20))'
```

Pass criteria:
- `claude.stop >= 1`
- `claude.turn_end >= 1`

Optional: inspect the `turn_end` payload to confirm reason:

```bash
python -c 'import json; p="/tmp/stop-test-cb9d/sse_lines.jsonl"; \
[print(json.loads(l)["line"]) or exit(0) for l in open(p) if json.loads(l).get("event")=="claude.turn_end"]; \
print("missing turn_end")'
```

### C) Regression: multiple runs don’t multiply stop/turn_end unexpectedly
Two separate invocations into the same log dir:

```bash
cd /Users/sotola/swe/claude-code-2.1.20-obs && \
  rm -rf /tmp/stop-test-cb9d && \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 node cli.js --log-dir /tmp/stop-test-cb9d -p "one" && \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 node cli.js --log-dir /tmp/stop-test-cb9d -p "two"
```

Then recount: expect roughly 2 `claude.stop` + 2 `claude.turn_end`.

### D) Main-agent-only constraint (best-effort)
This is harder to validate without reliably triggering subagents, so treat it as a “proof by code + spot-check”:

- Code proof:
  - `__cc_shouldEmitMainStopHook` must hard-reject `agentId && !__cc_isMainAgent(agentId)`
- Spot-check:
  - Trigger any workflow that produces sidechain/subagent activity (whatever you use operationally).
  - In the resulting `/tmp/.../sessions.jsonl`, look for entries that indicate subagents (e.g., sidechain/subagent session files) and confirm `sse_lines.jsonl` still only shows one stop/turn_end per main prompt.

---

## Done When
- A normal main-agent prompt produces `claude.stop` + `claude.turn_end` in `sse_lines.jsonl`.
- Subagent work does not generate extra stop/turn_end events (enforced by the strict main-agent gating).

### User Prompt #1
Can you tell me in simple terms what this means for our implementation? Be less event oriented, don't quote specific code terms unless I specifically asfor "proof" or how did you know this. Mention the pattern and evaluate the risk. Always link the information you're presenting towards our goal. This should be a slightly technical executive summary. You could mention core arthitectural artifacts, but don't go into details.

### 2. The Pivot (Good Content, Weak Format)
*Content is much better and answers the "executive" need, but formatting is plain and text-heavy.*

Right now, the port to 2.1.20 is succeeding at “high-volume observability” (streaming output, tool results, normalized JSONL, version-tagged metadata), but it’s missing a key “turn is finished” signal that our pipeline uses to close out a user interaction cleanly.

What this means for our goal (reliable, comparable logs across versions):
- We can see *what happened during a turn*, but in 2.1.20 we often can’t reliably tell *when the main turn ended*, so downstream counting/analytics will under-report completed turns and can treat sessions as “hanging.”
- The underlying stop-hook mechanism is still present and running (so product behavior is fine), but our observability layer is not currently “listening” at the one place where stop hooks conclude, so the end-of-turn marker never gets emitted for the edited 2.1.20 build.
- This is consistent with the version-tagged log ratios: 2.1.15 shows those end-of-turn markers; 2.1.20 (edited) shows essentially none in the same sampled slice.

Pattern to fix (and why it matches the goal):
- Reconnect a small bridge at the single “stop-hook completed / cancelled / blocked continuation” chokepoint so we emit exactly one end-of-turn marker.
- Add a strict “main-agent only” gate so subagents don’t produce duplicate end markers in swarm/multi-agent flows.

Risk assessment:
- Product risk: low (it’s best-effort logging; should be wrapped so it can’t break execution).
- Observability risk: medium if we wire the bridge in the wrong place or gate incorrectly (double-counting in multi-agent runs, or missing markers on some paths). This is testable with a few targeted runs.

What I did:
- Audited the 2.1.20 observability port against the requirements and the working 2.1.15 behavior.
- Verified via log-version metadata counts that 2.1.20 is missing the end-of-turn markers while 2.1.15 has them.
- Identified the exact architectural gap: the stop-hook completion path isn’t connected to our centralized observability emission in 2.1.20, and outlined how to reattach it with main-agent-only gating.

Are we handling the stop hook correctly (1–10)?
- 4/10 as of now: the stop-hook system exists and runs, but the observability “turn end” portion that we care about for this project goal isn’t wired in 2.1.20 yet.

Should there be more edits before we call this done?
- Yes: implement the bridge + main-agent-only gate, then run a small test suite that proves (a) one end marker per main turn, (b) no extra end markers from subagents, and (c) no regressions in normal CLI behavior.

### User Prompt #2
Good, Some improvement, how wever you should use ` and ** more, header should have ad slightly differnt formatting / color also, basically think of this a s a uman rtiendly md (don't put stuff in wrapped md block, just type things out like we're in a md file already 

example:

## Main Locations

| Location | Purpose |
|----------|---------|
| `/Users/sotola/db23_folder/` | Primary data storage (~90+ GB of pickles and transaction data) |
| `/Users/sotola/PycharmProjects/mac_local_m4/` | Pipeline Python scripts |
| `/Users/sotola/PycharmProjects/db23/` | Excel splitting utilities |

## Available Skills

You have three skills for working with db23:
- **`db23-pipeline`** - Run the 6-step data ingestion pipeline
- **`db23-excel-split`** - Split multi-day Excel files into single-day files
- **`db23-create-day-project`** - Create new Viber Stock OCR project folders

## Key Files

- `df_trans_numerical.pickle` (7.1 GB) - Master numerical transaction dataframe

now, try again

### 3. The Ideal (Executive Summary)
*Visual, readable, clear hierarchy. "Exactly what the user wants."*

## Executive Summary (Goal: Reliable “Turn Finished” Signals)

Right now, the `2.1.20-obs` port is **strong on “what happened during a run”** (stream deltas, tool results, normalized JSONL, version-tagged metadata), but **weak on “when the main turn is finished.”**

That missing “turn finished” marker is why `2.1.20` shows near-zero counts for the end-of-turn events compared to `2.1.15`, even though the underlying product behavior is fine.

## What This Means For Our Implementation

- We can reconstruct **outputs and tool activity**, but downstream analytics cannot reliably close a turn for the main agent.
- This undermines our goal of **comparability across versions** (`2.1.15` vs `2.1.20`) and can cause:
  - undercounted completed turns
  - sessions that look “stuck” or incomplete
  - noisier multi-agent metrics because “end” is the key delimiter

## Pattern (How We Fix It)

We need one small bridge:

- Hook into the **single stop-hook completion chokepoint** (the place where stop hooks finish / cancel / block continuation)
- Emit exactly **one end-of-turn marker**
- Guard it with **main-agent-only** logic so subagents don’t create duplicate “turn finished” markers

## Risk Evaluation (Tied To The Goal)

- **Product risk: low**  
  Logging is best-effort; it should never change runtime behavior.
- **Observability correctness risk: medium** (until tested)  
  The only meaningful failure modes are:
  - missing markers on one stop path (still “incomplete turns”)
  - double markers (inflated turn counts), especially in multi-agent/swarm flows

Both are straightforward to validate with targeted tests.

## What I Did

- Audited `2.1.20-obs` against the `2.1.15` working behavior and the stated requirements.
- Used the `metadata.ver` field in `sse_lines.jsonl` to compare event distributions between:
  - `claude-code-2.1.15` (previous working instrumentation)
  - `claude-code-2.1.20` (current edited build)
- Confirmed the exact gap: **the stop-hook lifecycle is present**, but **our observability emission for “turn finished” is not wired into that lifecycle** in `2.1.20-obs`.

## Are We Handling Stop Hooks Correctly?

- **Stop-hook behavior (product): 8/10**  
  The stop-hook system itself is still there and functioning.
- **Stop-hook observability (our goal): 4/10**  
  We’re missing the main “turn finished” markers that make logs comparable and analyzable.

## Should We Do More Edits Before Calling It Done?

Yes.

**Minimum “done” bar for our goal:**
- Each main-agent turn produces exactly:
  - one “stop” marker
  - one “turn end” marker
- Subagents produce **no extra** “turn end” markers
- No regressions in normal CLI operation

Once the bridge + main-agent gate is implemented and those tests pass, we can call the stop-hook portion “done.”

---

# Modes (How to Use This Skill)

Use this skill to tailor the output format based on user intent.

## 1. Mode: "Executive Summary"
**Trigger**: User asks for "executive summary", "high level report", "simple terms", or "executive tone".
**Action**: Mimic **Answer #3**.
- Use clear Markdown headers (`##`).
- Use bold (`**`) for key takeaways and metrics.
- Focus on "What This Means", "Risk", "Pattern", "Score".
- **Avoid** code blocks, line numbers, or dense technical logs unless explicitly requested.

## 2. Mode: "Technical Report"
**Trigger**: User asks for "technical report", "implementation details", "proof", "audit results", or "dense report".
**Action**: Mimic **Answer #1**.
- Include file paths, line numbers, function names.
- Provide code snippets/diffs.
- Detailed implementation plan and testing guide.
- Verification steps with commands.

## 3. Mode: "Complete Report"
**Trigger**: User asks for "complete report", "full report", "detailed report with summary".
**Action**: Combine **Answer #3** AND **Answer #1**.
- **Part 1**: The Executive Summary (Style 3).
- **Part 2**: The Technical Details (Code, Implementation Plan, Tests).
- Use a clear horizontal separator (`---`) or major headers to distinguish the two sections.