Skill: ivangdavila/metrics (version 1.0.0)

--- name: Metrics slug: metrics version: 1.0.0 homepage: https://clawic.com/skills/metrics description: Capture, normalize, and report metrics across any domain with reusable dimensions, programmable formulas, and scalable reporting workflows. changelog: Initial release with metric registry design, formula governance, and automation-ready reporting workflows. metadata: {"clawdbot":{"emoji":"📊","requires":{"bins":[]},"os":["linux","darwin","win32"]}} --- ## Setup On first use, read `setup.md` for integration behavior and memory initialization. ## When to Use Use this skill when the user needs to define, track, analyze, or report metrics for any domain such as social media, sales, product, operations, finance, or personal systems. This skill structures metric definitions, computes reliable formulas, builds reusable report packs, and maintains scalable automation rules that can grow with the user over time. ## Architecture Working memory lives in `~/metrics/`. See `memory-template.md` for base structure and status behavior. ``` ~/metrics/ ├── memory.md # HOT: goals, active metrics, reporting cadence ├── registry/ # WARM: metric contracts and dimension dictionaries ├── formulas/ # WARM: formula specs with version history ├── reports/ # WARM: report outputs by cadence and stakeholder ├── automations/ # WARM: scheduled checks and alert policies └── archive/ # COLD: retired metrics and old report cycles ``` ## Quick Reference Load only the file needed for the current task to keep context focused. | Topic | File | |-------|------| | Setup and integration | `setup.md` | | Memory schema | `memory-template.md` | | Metric contract design | `metric-registry.md` | | Formula design and governance | `formula-playbook.md` | | Report cadences and templates | `reporting-pack.md` | | Automation and alerting patterns | `automation-patterns.md` | | Data validation and quality gates | `data-quality.md` | ## Core Rules ### 1. Define a Metric Contract Before Any Calculation Every metric must have one clear contract: business meaning, numerator, denominator, source tables, update latency, and owner. Never compute or compare metrics when the contract is missing or ambiguous. ### 2. Separate Raw Signals from Derived Metrics Raw events are evidence. Metrics are interpreted aggregates. Keep them separate. Store and reason in this order: 1. Raw signal 2. Normalized base metric 3. Derived metric 4. Decision recommendation ### 3. Use Dimensions to Scale, Not New One-Off Metrics When users ask for "the same metric but by X", add a dimension instead of creating a duplicate metric. Common high-value dimensions: - Time grain - Source/channel - Segment/persona - Geography - Product or workflow stage ### 4. Version Formulas and Annotate Breaking Changes Formulas evolve. Comparability fails when formula changes are not tracked. For every formula update, store: - version - change reason - impact expectation - backfill policy - first report date with new logic ### 5. Reports Must Be Decision-Oriented A report is incomplete unless each section ties to a decision owner and explicit next action. Minimum output block for every report: - What changed - Why it changed - What to do now - Who owns the action - When to review again ### 6. Automate Thresholds with Response Playbooks Alerts without response rules create noise. Each threshold must include: - trigger condition - severity level - owner - first response action - escalation condition ### 7. Prefer Reusable Reporting Packs Over Custom One-Offs Build reusable templates for daily, weekly, monthly, and campaign reports so the system can scale across teams and domains. Only create custom formats when a stakeholder decision cannot be served by existing packs. ## Common Traps - Mixing different metric definitions under one name -> trend lines become invalid. - Changing formulas without version notes -> historical comparisons break silently. - Reporting totals without segment cuts -> root causes remain hidden. - Creating too many vanity metrics -> operators lose focus on decision metrics. - Sending alerts without action ownership -> teams ignore notifications. - Adding one-off dashboards for every request -> reporting system becomes unmaintainable. ## Security & Privacy **Data that leaves your machine:** - None by default. **Data that stays local:** - Metrics context and definitions under `~/metrics/`. - Formula versions, report logs, and alert policies stored locally. **This skill does NOT:** - Access files outside `~/metrics/` for memory storage. - Send metrics to third-party APIs by default. - Create background automations without explicit user confirmation. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `analytics` — metric analysis patterns and interpretation workflows. - `dashboard` — KPI visualization design and reporting layouts. - `report` — structured reporting outputs for stakeholders. - `sql` — query generation for metric extraction pipelines. - `excel-xlsx` — spreadsheet-based metric operations and exports. ## Feedback - If useful: `clawhub star metrics` - Stay updated: `clawhub sync`

path: automation-patterns.md
content: # Automation Patterns

Use these patterns to keep metric workflows scalable without alert fatigue.

## Automation Layers

| Layer | Purpose | Typical Trigger |
|-------|---------|-----------------|
| Collection | Refresh metric inputs | schedule or source update |
| Validation | Run quality gates | post-refresh |
| Reporting | Generate summary output | fixed cadence |
| Alerting | Escalate material deviations | threshold or anomaly |
| Learning | Update policy from outcomes | post-incident review |

## Trigger Design Rules

- Keep triggers tied to decision value, not data volume.
- Separate warning and critical thresholds.
- Add cooldown windows to avoid repeated noise.
- Attach owner and first response action to every trigger.

## Severity Model

| Severity | Condition | Response Target |
|----------|-----------|-----------------|
| Info | Small variance within normal range | Document and monitor |
| Warning | Variance likely requiring action | Owner reviews in next cycle |
| Critical | Breach with business impact | Immediate response and escalation |

## Escalation Template

When a critical trigger fires:

1. Confirm data validity before action.
2. Notify owner with impacted metrics and segments.
3. Run first response playbook.
4. Escalate if not stabilized by agreed SLA.
5. Log resolution and prevention step.

## Automation Hygiene

- Review thresholds monthly to reduce stale rules.
- Retire triggers that never lead to decisions.
- Track false-positive rate by policy.
- Record postmortems for major metric incidents.


path: data-quality.md
content: # Data Quality Gates

Use this checklist before computing formulas or shipping reports.

## Core Quality Checks

Run in this order:

1. Completeness: expected rows and fields are present.
2. Freshness: data timestamp is within allowed latency.
3. Uniqueness: keys are not duplicated unexpectedly.
4. Consistency: units and value scales match definitions.
5. Reconciliation: segment sums match top-line totals.

## Drift Detection

Detect drift for each critical metric:

- Definition drift: source logic changed without version note.
- Distribution drift: value profile shifted beyond expected band.
- Pipeline drift: refresh latency or missing partitions increased.

## Scorecard Template

| Check | Status | Severity | Owner | Action |
|-------|--------|----------|-------|--------|
| Freshness | pass/fail | warning/critical | name | response |
| Completeness | pass/fail | warning/critical | name | response |
| Reconciliation | pass/fail | warning/critical | name | response |

## Release Rule

If any critical quality check fails:

- Block report publication.
- Publish incident summary instead of metric values.
- Route owner to investigation workflow.

## Incident Note Template

- Metric affected:
- Check failed:
- Suspected root cause:
- Immediate mitigation:
- ETA for fix:
- Confidence in current numbers:


path: formula-playbook.md
content: # Formula Playbook

Use this playbook to design robust formulas and avoid silent drift.

## Formula Spec Template

For each formula, document:

- Formula name
- Version
- Input metrics
- Exact equation
- Null and zero handling
- Output unit
- Expected range
- Failure modes
- Backfill policy

## Formula Categories

| Category | Purpose | Example |
|----------|---------|---------|
| Base ratio | Compare two aligned quantities | conversion_rate = converted / qualified |
| Efficiency | Relate output to cost | revenue_per_employee |
| Quality index | Weighted composite health signal | support_quality_index |
| Trend velocity | Measure direction and speed | week_over_week_delta |
| Forecast helper | Project near-term outcomes | run_rate_projection |

## Governance Rules

- Version every formula change, even small edits.
- Keep old and new formulas side by side during transition periods.
- Annotate why the change happened and expected directional impact.
- Mark metrics as "not comparable" across periods when formulas changed.

## Guardrail Patterns

Use guardrails to prevent invalid outputs:

- Denominator zero -> return null and explanation.
- Missing input over threshold -> block report publication.
- Outlier surge over defined z-score -> add anomaly flag.
- Unit mismatch -> fail fast and request normalization.

## Example Formula Block

```text
name: creator_efficiency_index
version: v1.2.0
equation: (qualified_leads * avg_deal_value) / content_hours
null_policy: block_if_missing_input_gt_5_percent
expected_range: 0 to 10000
change_reason: aligned lead qualification criteria with sales SLA
```

## Formula Review Checklist

- Equation answers the intended business question.
- Inputs are available at the target cadence.
- Unit conversions are explicit.
- Edge cases are defined.
- Version note is logged.


path: memory-template.md
content: # Memory Template - Metrics

Create `~/metrics/memory.md` with this structure:

```markdown
# Metrics Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | done | declined

## Operating Context
- Domain focus:
- Decision horizon: daily | weekly | monthly | quarterly
- Main stakeholders:
- Current primary objective:

## Metric Registry Index
| Metric | Owner | Grain | Segment Lens | Source | Health |
|--------|-------|-------|--------------|--------|--------|
| Example: Activation Rate | Growth | Weekly | Channel | warehouse.events | green |

## Formula Inventory
| Formula | Version | Inputs | Guardrails | Last Change |
|---------|---------|--------|------------|-------------|
| Example: CAC Payback | v1.0.0 | spend, gross margin | null checks | YYYY-MM-DD |

## Reporting Calendar
- Daily report owner:
- Weekly report owner:
- Monthly report owner:
- Last report date:

## Alert Policies
- Trigger:
  Severity:
  Owner:
  First response:
  Escalation path:

## Decision Log
- Date:
  Decision:
  Metric signal:
  Confidence:
  Follow-up date:

## Backlog
- [ ]
- [ ]

## Notes
- Stable context and constraints worth retaining.
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Context still evolving | Keep collecting context while shipping useful outputs |
| `complete` | Baseline is stable | Focus on execution and continuous optimization |
| `paused` | User postponed setup | Continue work without setup prompts |
| `never_ask` | User opted out permanently | Never ask setup questions again |

## Memory Hygiene

- Store decisions and definitions, not raw chat transcripts.
- Keep formula history auditable with short version notes.
- Archive retired metrics instead of deleting context.


path: metric-registry.md
content: # Metric Registry Guide

Use this guide to define scalable metric contracts.

## Metric Contract Template

For every metric, record:

- Metric name
- Business question answered
- Owner
- Time grain (hourly, daily, weekly, monthly)
- Numerator definition
- Denominator definition (if ratio)
- Required dimensions
- Data source and refresh latency
- Data quality risks
- Review cadence

## Dimension Taxonomy

Use a fixed taxonomy so metrics stay reusable:

| Dimension Class | Examples |
|-----------------|----------|
| Time | date, week, month, quarter |
| Entity | user, account, team, region |
| Acquisition | channel, campaign, source |
| Product | feature, plan, lifecycle stage |
| Commercial | price tier, contract type, ACV band |

If a new request fits an existing class, extend values, not schema.

## Naming Rules

- Use plain names: `activation_rate`, `gross_revenue_retention`, `avg_resolution_time`.
- Keep suffixes consistent: `_count`, `_rate`, `_share`, `_amount`, `_index`.
- Never reuse a retired metric name without a version qualifier.

## Registry Health Check

Run this check before adding a metric:

1. Does this metric map to a decision?
2. Is there one owner?
3. Are numerator and denominator explicit?
4. Can the same question be answered with an existing metric + dimension?
5. Is refresh latency acceptable for the decision cadence?

If any answer is no, redesign before adding.

## Domain Examples

- Social media: engagement rate by platform and content type.
- Product: activation rate by onboarding path.
- Sales: win rate by segment and rep.
- Operations: SLA breach rate by queue and severity.
- Personal systems: weekly habit completion rate by category.


path: reporting-pack.md
content: # Reporting Pack

Use this file to build reusable report outputs that scale.

## Cadence Model

Define one pack per cadence and audience:

| Cadence | Audience | Main Decision |
|---------|----------|---------------|
| Daily | Operators | Immediate corrections |
| Weekly | Managers | Priority and resource allocation |
| Monthly | Executives | Strategy and investment direction |
| Campaign | Cross-functional team | Launch optimization |

## Standard Report Block

Every report should include these sections:

1. Headline metrics (top 3-7)
2. Largest movements vs prior period
3. Segment breakdown showing where change came from
4. Drivers and confidence level
5. Recommended actions with owner and due date
6. Risks and data quality caveats

## Output Shapes

Choose the shape that matches the decision speed:

- Fast pulse: concise bullet digest for daily operations.
- Narrative brief: cause-and-effect summary for weekly reviews.
- Board summary: directional trends, risk, and strategic bets.
- Diagnostic appendix: metric definitions and data quality details.

## Report Quality Gates

Before publishing any report:

- All headline metrics pass definition checks.
- Formula versions are listed.
- Comparison windows are aligned.
- Segment totals reconcile with overall totals.
- Recommendations have owner and review date.

## Decision Readiness Test

A report is decision-ready only if a stakeholder can answer:

- What changed?
- Why did it change?
- What should happen next?
- Who owns the next action?
- When will impact be reviewed?


path: setup.md
content: # Setup - Metrics

Read this when `~/metrics/memory.md` does not exist or is empty.

Start naturally by asking what the user wants to measure first and what decision those metrics should improve.

## Integration First

Early in the conversation, confirm activation behavior:

- Should this support activate whenever the user discusses KPIs, dashboards, formulas, tracking, or reporting?
- Should it proactively suggest missing metrics and quality checks, or respond only when asked?
- Should metric decisions be logged by default for future sessions?

If the user declines setup details, continue immediately and set integration to `declined`.

## Capture the Minimum Useful Baseline

Collect only high-impact baseline context:

- Domain focus: business, product, marketing, operations, finance, personal, or mixed.
- Primary outcome goals for the next review period.
- Current data sources and update frequency.
- Main reporting audience: operator, manager, executive, client, or mixed.
- Current pain point: unclear definitions, data inconsistency, noisy alerts, or slow reporting.

Ask one focused question at a time. Prioritize fast usefulness over exhaustive intake.

## First-Session Output

Before ending setup, deliver one actionable artifact:

- A metric registry starter with 5-10 high-value metrics.
- A first formula catalog with clear contracts and owners.
- A reporting cadence plan with daily, weekly, and monthly outputs.
- An alert policy draft with severity tiers and response ownership.

## Persistence Rules

When memory is enabled:

- Create `~/metrics/memory.md` from `memory-template.md`.
- Update `last` after meaningful progress.
- Keep notes short, decision-oriented, and version-aware.
- Never store secrets, credentials, or unrelated personal data.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)