reporting

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# Reporting

Turn live operating data into compact reports that answer one practical
question:

- what changed
- why it matters
- what needs action now

Do not produce reporting theater. A report is only credible when it is grounded
in live or recently fetched data from the systems that actually run the
business.

## Core Reporting Loop

Use this loop for every report, regardless of domain:

1. define the reporting frame: period, audience, operating question
2. load prior state, baselines, or thresholds
3. fetch current data from source systems
4. compare current state against prior state, targets, or seen items
5. isolate the few deltas that actually matter
6. turn those deltas into decisions, owners, and escalations
7. save enough state for the next run when the report is recurring

If the task is recurring, the report should feel like a checkpoint, not a reset.

## First Run Vs Recurring Run

Treat recurring reporting as a tracked system.

On a first run:

- define the operating question and cadence
- collect the minimum baseline needed for next time
- ask for or infer targets, categories, thresholds, or tracked entities
- save only the state required to make the next run comparative

On later runs:

- load the last snapshot before fetching new data
- identify what is new, changed, completed, or still unresolved
- avoid repeating previously seen items unless their status worsened or they now
  require a decision
- update the saved state at the end of the run

Do not ask the user to restate stable tracking context every time if the task is
clearly part of a cadence.

## Reporting Memory Contract

When the report is recurring, preserve only the state that improves the next
run. Typical stored fields:

- `last_run_at`
- `reporting_window`
- `previous_totals` or prior KPI snapshot
- `targets`, thresholds, or pacing assumptions
- tracked entities such as channels, vendors, goals, or keywords
- `seen_ids`, `seen_urls`, or previously reported items
- unresolved risks, open asks, and named owners

Good recurring reports know what changed since the last run without redoing the
entire setup.

## External Data Requirement

For proper reporting, connect to the source systems instead of relying on stale
memory, copied summaries, or guessed numbers.

Preferred integration order:

1. **CLI first**: use the system's CLI when it is available and trustworthy.
2. **MCP second**: use MCP tools when they provide cleaner or richer access.
3. **API last**: call direct APIs only when CLI and MCP cannot provide the
   required coverage.

Rules:

- Do not claim a report is current unless you actually fetched current data.
- Do not invent values for unavailable systems.
- If a required system is unreachable, say which part of the report is degraded.
- If the source of truth is ambiguous, name the system you chose and why.
- For recurring reports, record what point in time the data reflects.

## Use This Skill For

- weekly team or functional updates
- monthly operating reviews
- board or investor updates
- QBRs and business performance summaries
- KPI dashboards that need narrative, not a metric dump
- executive escalation memos with a clear ask
- engineering delivery reporting: PR queue, review latency, merge conflicts, CI,
  and release readiness
- product analytics reporting: KPI hierarchy, cohort and retention reviews,
  funnel health, feature adoption, and release-impact analysis
- monthly expense reporting from receipts, invoices, or finance notifications
- savings-goal check-ins against targets and current pace
- audience growth reports by channel or segment
- engagement analysis by content type, format, or platform
- social mention monitoring, testimonial collection, and brand-signal reporting

## Typical Source Systems

Common external inputs include:

- `git`, GitHub CLI, CI CLIs, deployment tooling
- issue trackers such as Linear, Jira, or internal ticketing systems
- spreadsheets, BI exports, finance systems, and warehouse query outputs
- inboxes, receipt emails, invoices, bank notifications, and statement exports
- CRM, support, social, analytics, and community platforms
- team status notes only after the operating data has been collected

When multiple systems disagree, prefer the one closest to execution:

- merged PRs over status notes
- issue tracker state over a slide
- warehouse numbers over manually edited summaries

From alvarovillalbaa/afs, MIT.

More from alvarovillalbaa/afs