bradfeld/ceos/ceos-trends

ceos-trends

Longitudinal EOS health tracking - analyze how your organization is improving over time across all Six Key Components. While ceos-dashboard shows today's snapshot, ceos-trends answers the question every EOS coach asks: "Are we getting better?"

When to Use

• "How are we trending?" or "show our progress"
• "Are we improving?" or "EOS health over time"
• "Quarter comparison" or "compare Q1 to Q2"
• "Rock completion history" or "how have our rocks been?"
• "Scorecard trends" or "are our numbers improving?"
• "Show trends" or "progress report"
• Before quarterly planning or annual planning for historical context

Context

Finding the CEOS Repository

Search upward from the current directory for the .ceos marker file. This file marks the root of the CEOS repository.

If .ceos is not found, stop and tell the user: "Not in a CEOS repository. Clone your CEOS repo and run setup.sh first."

Sync before use: Once you find the CEOS root, run git -C <ceos_root> pull --ff-only --quiet 2>/dev/null to get the latest data from teammates. If it fails (conflict or offline), continue silently with local data.

Key Files

Design Principles

• Read-only. Trends never modifies any data files. It reads, calculates, and reports.
• Graceful degradation. Works with whatever data exists. One quarter of Rocks? Show that. No checkups yet? Skip that section with guidance. Never error on missing data.
• Cross-skill coordination. Each trend section suggests the relevant skill for taking action. Trends shows the trajectory; other skills change it.
• Minimum data threshold. For meaningful trends, at least 2 data points are needed (e.g., 2 quarters of Rocks, 2 checkups). With only 1 data point, show the baseline value and note: "More data needed for trend analysis."

Quarter and Week Calculations

• Current quarter: Jan-Mar = Q1, Apr-Jun = Q2, Jul-Sep = Q3, Oct-Dec = Q4. Format: YYYY-QN
• Current ISO week: Format: YYYY-WNN
• Available quarters: Scan data/rocks/ subdirectory names to discover all quarters with data.
• Trailing periods: "Trailing 4 weeks" = most recent 4 weekly scorecard files. "Trailing 13 weeks" = most recent 13 (approximately one quarter).

Process

Mode: Overview (default)

Use when the user asks for a general trend summary. This is the default when no specific component is mentioned.

Step 1: Discover Available Data

Scan the CEOS data directories to determine what historical data exists:

1. Quarters with Rocks: List subdirectories in data/rocks/ matching YYYY-QN pattern. Sort chronologically.
2. Scorecard weeks: List files in data/scorecard/weeks/ matching YYYY-WNN.md. Sort chronologically.
3. Checkups: List files in data/checkups/ matching YYYY-MM-DD.md. Sort by date.
4. Issues: Count files in data/issues/open/ and data/issues/solved/.
5. To-Dos: List files in data/todos/. Parse created and completed_on dates.
6. L10 meetings: List files in data/meetings/l10/ matching YYYY-MM-DD.md.

If no historical data exists at all, show:

No EOS data found. Run your first L10, set some Rocks, or log a scorecard to start building history.

Step 2: Rock Completion Trend

For each quarter directory in data/rocks/:

1. Read all .md files in the directory.
2. Parse YAML frontmatter for status field.
3. Count: complete, on_track, off_track, dropped, total.
4. Calculate completion rate: complete / (total - dropped) as percentage.

For the current quarter (not yet ended), mark as "in progress" and show current status breakdown instead of a final completion rate.

Display:

Rock Completion
  2025-Q3: 4/6 complete (67%)
  2025-Q4: 5/7 complete (71%) ↑
  2026-Q1: 2 on track, 1 off track, 1 complete of 6 (in progress)

Trend arrows (compare each quarter to the previous):

• ↑ = completion rate improved
• → = unchanged (within 5 percentage points)
• ↓ = completion rate declined

If only one quarter exists: Show the data without trend arrows. Add: "Track Rocks across multiple quarters to see completion trends."

If no Rock directories exist:

Rock Completion: No Rock data yet. Run `ceos-rocks` to set quarterly priorities.

Step 3: Scorecard Consistency

Analyze scorecard data across available weeks:

1. Read all weekly scorecard files from data/scorecard/weeks/.
2. For each file, parse the metrics table from the markdown body.
3. For each metric row, determine if it was on-track or off-track based on the status or value vs. threshold.
4. Calculate per-week: total metrics, on-track count, on-track percentage.

Calculate rolling averages:

• Trailing 4 weeks: Average on-track percentage over the last 4 weeks.
• Prior 4 weeks: Average on-track percentage for the 4 weeks before that.
• Trailing 13 weeks: Average on-track percentage over the last 13 weeks (quarter).

Also calculate logging consistency:

• Count weeks with scorecard entries vs. total weeks in the period.

Display:

Scorecard Consistency
  Weeks logged: 24/26 (92%)
  On-track rate (trailing 4 weeks): 78%
  On-track rate (prior 4 weeks): 71% ↑
  On-track rate (trailing 13 weeks): 74%

Trend arrow compares trailing 4 weeks to prior 4 weeks.

If fewer than 2 weeks of data exist:

Scorecard Consistency: [N] week(s) logged. Log more weeks for trend analysis.

If no scorecard data exists:

Scorecard Consistency: No scorecard data yet. Run `ceos-scorecard` to start tracking weekly.

Step 4: Checkup Score Progression

Read all checkup files from data/checkups/:

1. Parse YAML frontmatter for overall_score and component_scores.
2. Sort by date.
3. Show score progression over time.

Display:

Checkup Scores
  2025-09-15: 3.2 overall (Vision: 3.5, People: 3.0, Data: 3.2, Issues: 3.0, Process: 2.8, Traction: 3.5)
  2025-12-20: 3.8 overall (+0.6) ↑↑ (Vision: 4.0, People: 3.5, Data: 3.8, Issues: 3.5, Process: 3.2, Traction: 4.0)
  2026-03-01: 4.2 overall (+0.4) ↑ (Vision: 4.5, People: 4.0, Data: 4.2, Issues: 4.0, Process: 3.5, Traction: 4.3)

Trend indicators (compare to previous checkup):

• ↑↑ = improved by 0.5+
• ↑ = improved by 0.1-0.4
• → = unchanged (within 0.1)
• ↓ = declined by 0.1-0.4
• ↓↓ = declined by 0.5+

If only one checkup exists: Show the score without trend arrows. Add: "Run another organizational checkup to track progress over time."

If no checkups exist:

Checkup Scores: No checkups on file. Run `ceos-checkup` to assess organizational health.

Step 5: Issue Resolution Velocity

Analyze issues from both data/issues/open/ and data/issues/solved/:

1. Read all issue files from both directories.
2. Parse YAML frontmatter for created date and priority.
3. For solved issues, calculate resolution time (days between created and the file's most recent frontmatter date or git modification).
4. Group by quarter based on created date.

Calculate per-quarter:

• Issues opened
• Issues solved
• Net change (solved - opened; negative means backlog grew)
• Average days to resolve (for solved issues)

Display:

Issue Resolution
  2025-Q4: 8 opened, 10 solved (net: -2, backlog shrinking) | Avg resolution: 24 days
  2026-Q1: 5 opened, 7 solved (net: -2, backlog shrinking) | Avg resolution: 18 days ↑
  Currently open: 4 issues (oldest: 12 days)

Trend arrow on resolution time (lower is better):

• ↑ = resolution time decreased (improving)
• → = unchanged (within 3 days)
• ↓ = resolution time increased (slowing down)

If no issues exist (open or solved):

Issue Resolution: No issues tracked yet. Use `ceos-ids` to identify, discuss, and solve issues.

Step 6: To-Do Completion Rate

Analyze to-do files from data/todos/:

1. Read all to-do files.
2. Parse YAML frontmatter for status, created, due, and completed_on.
3. Group by week based on due date.
4. Calculate weekly completion rate: complete / total for each week.

Calculate rolling averages:

• Trailing 4 weeks: Average completion rate.
• Trailing 13 weeks: Average completion rate.

EOS target is 90%+ weekly completion rate.

Display:

To-Do Completion Rate
  Trailing 4 weeks: 88% (target: 90%)
  Trailing 13 weeks: 82%
  Total: 45 complete / 52 created (87% all-time)

Color-code against the 90% target:

• At or above 90%: on target
• 80-89%: close, note the gap
• Below 80%: flag for attention

If no to-do data exists:

To-Do Completion Rate: No to-dos tracked yet. Use `ceos-todos` or run an L10 to create to-dos.

Step 7: L10 Meeting Cadence

Analyze L10 meeting files from data/meetings/l10/:

1. List all files matching YYYY-MM-DD.md.
2. Count meetings per quarter.
3. Calculate cadence: meetings held vs. weeks in the period.

Display:

L10 Meeting Cadence
  2025-Q4: 11/13 weeks (85%)
  2026-Q1: 9/10 weeks so far (90%)
  Streak: 6 consecutive weeks

Calculate current streak: consecutive weeks (from most recent backward) with an L10 file.

If no L10 files exist:

L10 Meeting Cadence: No L10 meetings on file. Run `ceos-l10` to start your weekly meetings.

Step 8: Trend Summary

After all sections, provide a categorized summary:

Trend Summary:
  Improving: Checkup scores (+0.4), Issue resolution (24 → 18 days), Scorecard consistency (71% → 78%)
  Stable: L10 cadence (90%)
  Needs attention: Rock completion (71% → in progress at 50%), To-do rate (88%, target 90%)

Categorize each component:

• Improving: Trend arrow is ↑ or ↑↑
• Stable: Trend arrow is → or insufficient data for comparison
• Needs attention: Trend arrow is ↓ or ↓↓, or below target thresholds

Then suggest actions only for "needs attention" items:

Suggested Actions:
  - Review off-track Rocks with `ceos-rocks`
  - Push to-do completion above 90% with `ceos-todos`

Mode: Deep Dive

Use when the user asks about a specific component's history (e.g., "Rock history", "scorecard trends in detail").

Step 1: Identify Component

If unclear, ask: "Which component do you want to explore? (Rocks, Scorecard, Checkups, Issues, To-Dos, L10)"

Step 2: Detailed Component Analysis

Run the relevant section from Overview mode but with expanded detail:

Rocks Deep Dive:

• Show each quarter's Rocks individually (title, owner, status)
• Show per-person completion rates across quarters
• Highlight people who consistently complete vs. miss Rocks

Scorecard Deep Dive:

• Show each metric's on-track percentage over time
• Identify consistently off-track metrics
• Show week-by-week detail for the trailing 13 weeks

Checkup Deep Dive:

• Show each component's score across all checkups
• Identify the most-improved and least-improved components
• Show individual question scores if available