# Ticketing Insights

> Daily deep dive reports and velocity-based project completion estimates using Linear data

- Skill: `omninode-ai/ticketing-insights` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add omninode-ai/ticketing-insights`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omninode-ai/ticketing-insights/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OmniNode-ai (https://skillmd.com/u/omninode-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/omninode-ai/ticketing-insights

---


# Ticketing Insights

## Mode Declaration

**This skill operates in REPORTING mode only.**

Ticketing-insights is not a build skill and not a close-out skill. It reads data — from Linear,
GitHub, and git history — and produces reports. It does not implement features, merge PRs,
or modify worktrees.

Valid `--mode` values:
- `deep-dive` (default) — comprehensive daily work analysis
- `close-day` — end-of-day reconciliation (ModelDayClose YAML)
- `project` — project health dashboard
- `velocity` — milestone ETA calculations
- `suggest` — priority backlog recommendations
- `pipeline` — rework ratio, cycle time, CI stability
- `github` — PR counts, commit velocity, LOC metrics
- `all` — run every mode, produce combined report

**First output line** must always be:
```
[ticketing-insights] MODE: reporting | submode: <mode-value>
```

No tool calls, file reads, or bash commands may precede this output.

If an unrecognized `--mode` value is passed, emit:
```
ERROR: Unknown --mode value: <value>
Valid modes: deep-dive | close-day | project | velocity | suggest | pipeline | github | all
```
Then stop.

Unified analytics and reporting for the OmniNode platform. All reporting modes are subcommands of this single skill.

## Quick Start

```
/ticketing-insights                           # Default: deep-dive mode
/ticketing-insights --mode close-day          # End-of-day reconciliation (ModelDayClose YAML)
/ticketing-insights --mode project MVP        # Quick health dashboard
/ticketing-insights --mode velocity MVP       # Milestone ETA calculations
/ticketing-insights --mode suggest            # Priority backlog recommendations
/ticketing-insights --mode pipeline           # Rework ratio, cycle time, CI stability
/ticketing-insights --mode github             # PR counts, commit velocity, LOC metrics
/ticketing-insights --mode all                # Run every mode, produce combined report
```

## Modes

### `--mode deep-dive` (default)

Generate a comprehensive daily work analysis. See Deep Dive Report section below.

### `--mode close-day`

Auto-generates a `ModelDayClose` YAML from today's GitHub PRs, git activity, and invariant probes.
Absorbed from the former `close-day` skill.

**Invocation**: `/linear-insights --mode close-day [--date YYYY-MM-DD] [--dry-run]`

**Execution steps**:
1. Pull merged PRs across all OmniNode-ai repos for the target date
2. Fetch active-sprint Linear plan
3. Build `actual_by_repo` grouped by repo with ticket references
4. Detect **scope drift**: PRs with no ticket ref → `drift_detected` entry
5. Run `scripts/check_arch_invariants.py` (shared with CDQA-07) to probe reducers/orchestrators
6. Detect **golden-path progress** by reading `emitted_at` from `$ONEX_STATE_DIR/golden-path/TODAY/` artifact JSON files
7. Set unknown statuses to `"unknown"` and add entries to `corrections_for_tomorrow`
8. Validate against `ModelDayClose.model_validate()` (fails loudly on schema mismatch)
9. Write to `$ONEX_CC_REPO_PATH/drift/day_close/YYYY-MM-DD.yaml` or print with warning banner

**ONEX_CC_REPO_PATH behavior**: If not set, YAML is printed with a warning banner (file NOT written). If set and path exists, writes to the drift directory.

### `--mode project`

Quick health dashboard for Linear projects — progress, velocity, blockers, ETA, and confidence.
Absorbed from the former `project-status` skill.

**Invocation**: `/linear-insights --mode project [PROJECT] [--all] [--blockers] [--risks] [--confidence] [--json] [--emit]`

Supports `--emit` to relay workstream snapshots to Kafka via `onex-linear-relay`.

### `--mode velocity`

Calculate project velocity from historical data and estimate milestone completion dates.
Absorbed from the former `velocity-estimate` skill.

**Invocation**: `/linear-insights --mode velocity [PROJECT] [--all] [--confidence] [--history] [--weighted] [--method METHOD] [--json]`

Methods: `simple` (signal-grade), `priority` (signal), `points` (ETA-grade), `labels` (signal), `cycle_time` (ETA-grade).

### `--mode suggest`

Priority backlog recommendations — highest priority unblocked issues with repo-based prioritization.
Absorbed from the former `suggest-work` skill.

**Invocation**: `/linear-insights --mode suggest [--count N] [--project PROJECT] [--repo REPO] [--label LABEL] [--json]`

### `--mode pipeline`

Pipeline health metrics — rework ratio, cycle time, CI stability, and feature velocity.
Absorbed from the former `pipeline-metrics` skill.

**Invocation**: `/linear-insights --mode pipeline [--since YYYY-MM-DD] [--ticket TICKET-ID] [--repo REPO] [--format table|json]`

Metrics: Cycle Time (P50/P90), CI Clean Rate, Rework Cycles/Ticket, Feature Velocity, Skill Duration P50.

### `--mode github`

GitHub repository statistics — PR counts, commit velocity, contributor activity, LOC metrics.
Absorbed from the former `gather-github-stats` skill.

**Invocation**: `/linear-insights --mode github [--github-only] [--local-only] [--include-local-loc] [--include-private] [--output PATH]`

### `--mode all`

Runs every mode sequentially and produces a combined report. Useful for comprehensive end-of-sprint summaries.

## When to Use

- **End of day wrap-up**: `--mode deep-dive` or `--mode close-day`
- **Sprint planning**: `--mode velocity` for capacity planning
- **Milestone tracking**: `--mode project` for data-driven ETAs
- **What to work on next**: `--mode suggest` for prioritized backlog
- **Pipeline health check**: `--mode pipeline` for rework and CI metrics
- **Repo statistics**: `--mode github` for PR throughput and commit velocity
- **Retrospectives**: `--mode all` for comprehensive analysis

---

## Deep Dive Report

Generates a comprehensive analysis of work completed in a specified time period.
Format matches the established deep dive pattern (see `$ONEX_STATE_DIR/deep-dives/` for archive).

### Usage

```bash
# Today's deep dive (display only) — auto-discovers all active repos
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive

# Specific date (auto-discovers repos with activity on that date)
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive --date 2025-12-09

# Last N days (for weekly summary)
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive --days 7

# Save to default directory (omni_save)
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive --save

# Save to custom directory
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive --save --output-dir ~/reports

# JSON output for processing
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive --json

# Analyze specific repos only (overrides auto-discovery)
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive --repos omnibase_core,omniclaude
```

### Configuration

**Output Directory** (where reports are saved with `--save`):

| Method | Example | Priority |
|--------|---------|----------|
| `--output-dir` flag | `--output-dir ~/reports` | Highest |
| `LINEAR_INSIGHTS_OUTPUT_DIR` env | `export LINEAR_INSIGHTS_OUTPUT_DIR=~/reports` | Medium |
| Default | `$ONEX_STATE_DIR/deep-dives` | Lowest |

**Filename Pattern**: `{MONTH}_{DAY}_{YEAR}_DEEP_DIVE.md`
- Example: `DECEMBER_13_2025_DEEP_DIVE.md`

### Deep Dive Format

The deep dive follows a structured format with these sections:

#### 1. Executive Summary
- **Velocity Score**: 0-100 based on commit volume, PRs merged, issues completed
- **Effectiveness Score**: 0-100 based on strategic value of work completed
- **Overall Assessment**: 2-3 sentence summary of the day

#### 2. Repository Activity Overview
- Commits per repository
- PRs merged per repository
- Files changed and lines added/deleted
- Focus areas

#### 3. Major Components & Work Completed
For each PR merged:
- Status, Impact level (Critical/High/Medium/Low)
- Files changed, lines added/deleted
- Description of work
- Key components/features
- Linear tickets addressed
- Significance statement

#### 4. Detailed Commit Analysis
- Commits grouped by category (Contracts, Runtime, CI, etc.)
- Key individual commits with file counts

#### 5. Metrics & Statistics
- Total commits, PRs, files changed
- PR statistics table
- Linear ticket progress (closed/in-progress)
- Code quality metrics

#### 6. Work Breakdown by Category
- Percentage breakdown of work types
- Time/effort allocation

#### 7. Key Achievements
- Bullet points of major accomplishments
- Milestone progress

#### 8. Challenges & Issues
- Technical challenges encountered
- Process observations

#### 9. Velocity Analysis
- Positive/negative velocity factors
- Velocity score justification

#### 10. Effectiveness Analysis
- High-value work identified
- Strategic impact assessment
- Effectiveness score justification

#### 11. Lessons Learned
- Key takeaways from the day
- Insights for future work

#### 12. Next Day Preview
- Expected focus areas for tomorrow
- Upcoming priorities

#### 13. Appendix
- Complete commit log with timestamps
- PR details

### Example Output

```markdown
# December 13, 2025 - Deep Dive Analysis

**Date**: Friday, December 13, 2025
**Week**: Week of December 9-13, 2025
**Day of Week**: Friday

---

## Executive Summary

**Velocity Score**: 85/100
**Effectiveness Score**: 90/100

**Overall Assessment**: Strong day with 12 issues completed across MVP and Beta milestones.
Focus on code quality improvements and deprecation fixes. 6 PRs merged with comprehensive
test coverage improvements.

---

## Repository Activity Overview

### omnibase_core
**Total Commits**: 24
**PRs Merged**: 4 (PRs #184-188)
**Files Changed**: 156
**Lines Changed**: +8,234 / -2,891
**Focus Areas**: Deprecation fixes, purity violations, structured logging

### omnibase_spi
**Total Commits**: 8
**PRs Merged**: 2 (PRs #39-40)
**Files Changed**: 23
**Lines Changed**: +1,456 / -892
**Focus Areas**: EventBus protocol cleanup, test coverage

...
```

---

## Velocity Estimate

Calculates project velocity and estimates time to completion for milestones.

### Usage

```bash
# Estimate for MVP project
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/velocity-estimate --project "MVP"

# All milestones overview
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/velocity-estimate --all

# Include confidence intervals
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/velocity-estimate --project "MVP" --confidence

# JSON output
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/velocity-estimate --project "Beta" --json
```

### Metrics Calculated

| Metric | Description |
|--------|-------------|
| **Velocity** | Issues completed per day/week (rolling average) |
| **Backlog Size** | Remaining issues by status |
| **Burn Rate** | Current completion rate vs planned |
| **ETA** | Estimated completion date |
| **Confidence** | Low/Medium/High based on velocity variance |

### Velocity Calculation

Velocity is calculated using a weighted rolling average:
- Last 7 days: 50% weight (recent performance)
- Last 14 days: 30% weight (short-term trend)
- Last 30 days: 20% weight (baseline)

This balances recent momentum with historical patterns.

### Example Output

```markdown
# Velocity Report: MVP - OmniNode Platform Foundation

## Current Status
- **Total Issues**: 71
- **Completed**: 28 (39%)
- **In Progress**: 5
- **Backlog**: 38

## Velocity Metrics
- **7-day velocity**: 2.3 issues/day
- **14-day velocity**: 1.8 issues/day
- **30-day velocity**: 1.5 issues/day
- **Weighted velocity**: 2.0 issues/day

## Completion Estimate
- **Remaining Issues**: 43
- **Estimated Days**: 21.5 days
- **Target Date**: 2026-01-03
- **Confidence**: Medium (variance: 0.4)

## Velocity Trend
[Chart showing 30-day velocity trend]

Week of 12/02: ████████░░ 1.6/day
Week of 12/09: ██████████ 2.3/day (current)

## Risk Factors
- 5 issues blocked/waiting
- 2 urgent issues in backlog
- Holiday period may reduce velocity
```

---

## Estimation Accuracy (Factory Telemetry)

Three-layer factory telemetry that parses the deep dive archive for historical velocity, effectiveness, PR throughput, and fix-vs-feature trends. Requires `python3`.

### Three Data Layers

**Layer 1 (Deep Dive Archive):** Parsed at script time from `$ONEX_STATE_DIR/deep-dives/`. Handles three format eras (Dec 2025, Feb 2026, Mar 2026) with null-not-zero for missing data. This is the primary data source.

**Layer 2 (GitHub PRs):** The script outputs `gh pr list` commands with date-window filtering. The agent executes these to collect merged PR data for reconciliation.

**Layer 3 (Linear Done):** The script outputs Linear MCP call instructions (`state="Done"`). The agent executes these to compare archive evidence against Linear's Done state.

### Usage

```bash
# All data + agent instructions
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/estimation-accuracy

# Last 7 days
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/estimation-accuracy --week

# Date range
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/estimation-accuracy --from 2026-03-01 --to 2026-03-05

# Graphable JSON output
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/estimation-accuracy --json

# Step-by-step agent instructions
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/estimation-accuracy --generate
```

### CLI Flags

| Flag | Default | Purpose |
|------|---------|---------|
| `--days N` | all | Last N days of deep dive data |
| `--from DATE` | earliest | Start date (YYYY-MM-DD) |
| `--to DATE` | today | End date (YYYY-MM-DD) |
| `--week` | -- | Shorthand for `--days 7` |
| `--json` | off | Output structured JSON (graphable) |
| `--generate` | off | Output step-by-step agent instructions |
| `--deep-dive-dir DIR` | `$ONEX_STATE_DIR/deep-dives` | Deep dive archive path |

### Fix-vs-Feature Tracking

PRs are classified by deep dive category: capability/governance/observability count as **feature**, correctness/churn count as **fix**, docs are excluded from both. Weekly aggregation computes fix ratio per ISO week. Trend analysis requires >= 4 weeks of data; labels are `declining`, `stable`, `increasing`, or `insufficient_data`.

### JSON Output Keys

- `meta` -- period, deep dive count, generation timestamp
- `time_series` -- per-day entries with velocity, effectiveness, prs_merged, categories, parse_quality
- `fix_vs_feature` -- weekly aggregation with trend_slope and trend_label
- `throughput_by_repo` -- per-repo PR totals and daily averages (Era B/C only)
- `reconciliation` -- extracted ticket IDs and instructions for agent to fill GitHub/Linear data

See script header comments for full schema.

### Reconciliation

The reconciliation view computes a three-way set comparison using ticket identifiers: archive IDs (A), Linear Done IDs (B), and GitHub PR IDs (C). The script computes set A; the agent fills B and C after executing the Layer 2/3 instructions, then computes overlap, gap ratio, and tickets shipped but not closed in Linear.

---

## Data Sources

- **Deep dive archive**: `$ONEX_STATE_DIR/deep-dives/*_DEEP_DIVE.md` (Layer 1, parsed by script)
- **GitHub CLI**: `gh pr list` commands (Layer 2, agent-executed)
- **Linear MCP**: `tracker.list_issues` (Layer 3, agent-executed)
- `tracker.list_projects` - Project metadata
- `tracker.get_project` - Project details

No external databases or caches are used - all calculations are done on fresh Linear data.

---

## Implementation Notes

### For General-Purpose Agent Dispatch

These skills are designed to be invoked by general-purpose agents:

```
Task(
  subagent_type="general-purpose",
  description="Generate daily work report",
  prompt="Generate a daily work report for the last 24 hours.

    Use Linear MCP tools:
    1. tracker.list_issues with assignee='me' and updatedAt='-P1D'
    2. Categorize by status (Done, In Progress, Backlog)
    3. Extract PR links from attachments
    4. Group by repository from labels

    Format as markdown with:
    - Summary stats
    - Completed work section with PR links
    - In Progress section
    - Insights (velocity, blockers, focus areas)"
)
```

### Velocity Calculation Algorithm

```python
def calculate_velocity(issues_completed, period_days):
    """
    Weighted rolling average velocity.

    Args:
        issues_completed: List of (date, count) tuples
        period_days: Analysis period

    Returns:
        Weighted velocity (issues/day)
    """
    weights = {
        7: 0.50,   # Last week: 50%
        14: 0.30,  # Last 2 weeks: 30%
        30: 0.20,  # Last month: 20%
    }

    total = 0
    for period, weight in weights.items():
        period_issues = sum(c for d, c in issues_completed
                          if d >= now - timedelta(days=period))
        velocity = period_issues / min(period, period_days)
        total += velocity * weight

    return total
```

---

## Project Status — Kafka Emission (--emit)

The `project-status` skill supports a `--emit` flag that serializes a workstream snapshot
and relays it to Kafka via the `onex-linear-relay` CLI. This is the primary ingress path for
Linear workstream data into the ONEX event bus.

### Usage

```bash
# Show dashboard for MVP project + emit snapshot to Kafka
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/project-status MVP --emit

# All projects overview + emit
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/project-status --all --emit

# JSON output + emit (useful for scripting)
${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/project-status MVP --json --emit
```

### How Emission Works

1. After generating the status output, `--emit` serializes a snapshot to `/tmp/linear-snapshot-{timestamp}.json`:
   ```json
   {
     "workstreams": ["MVP", "Beta"],
     "project": "MVP - OmniNode Platform Foundation",
     "project_shortcut": "MVP",
     "source": "project-status",
     "generated_at": "2026-02-23T22:00:00+00:00"
   }
   ```
2. Calls `onex-linear-relay emit --snapshot-file /tmp/linear-snapshot-{timestamp}.json`
3. The relay publishes to `onex.evt.linear.snapshot.v1` (non-blocking, exits 0 even if Kafka is unreachable)

### Requirements

- `onex-linear-relay` must be installed and available on `PATH`
- Install via: `pip install omnibase_infra` (or `uv add omnibase_infra` in your project)
- Related: Phase 2 — effect nodes and CLIs in omnibase_infra

### IMPORTANT: Do NOT Call REST Endpoint

The `POST /api/linear/snapshot` endpoint in omnidash is **debug-only ingress**.
It must never be called from production code or skills. Use `--emit` (which calls
`onex-linear-relay`) as the only correct production path for Linear data into the event bus.

---

## Skills Location

**Claude Code Access**: `${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/`

**Executables**:
- `${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/deep-dive` - Daily deep dive generator
- `${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/velocity-estimate` - Velocity and ETA calculator
- `${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/estimation-accuracy` - Three-layer factory telemetry (requires python3)
- `${CLAUDE_PLUGIN_ROOT}/skills/ticketing_insights/project-status` - Quick health dashboard with Kafka emission support

---

## See Also

- Linear MCP tools: `tracker.*`
- Linear ticket skills: `${CLAUDE_PLUGIN_ROOT}/skills/linear/`
- PR review skills: `${CLAUDE_PLUGIN_ROOT}/skills/pr-review/`
- Deep dive archive: `$ONEX_STATE_DIR/deep-dives/`
- `onex-linear-relay` CLI — `omnibase_infra` package