Status Reporting
Gather -> aggregate -> present pattern for comprehensive project status across VCS, PRs, issues, CI.
<when_to_use>
- Starting work sessions (context refresh)
- Checking project/team activity
- Understanding PR/stack relationships
- Quick status overview before planning
- Reviewing recent changes across systems
- Understanding blockers
NOT for: deep-dive into specific items, real-time monitoring, single-source queries
</when_to_use>
<core_pattern>
Three-stage workflow:
- Gather - collect from multiple sources
- Aggregate - combine, filter, cross-reference by time/stack/status
- Present - format for scanning with actionable insights
Key principles:
- Multi-source integration (VCS + code review + issues + CI)
- Time-aware filtering (natural language -> query params)
- Stack-aware organization (group by branch hierarchy)
- Scannable output (visual indicators, relative times)
- Actionable insights (highlight blockers, failures)
</core_pattern>
Stage 1: Parse Constraints
Extract time from natural language:
- "last X hours" ->
-Xh - "past X days" / "last X days" ->
-Xd - "yesterday" ->
-1d - "this morning" / "today" ->
-12h - "this week" ->
-7d - "since {date}" -> calculate days back
Default: 7 days if unspecified.
Stage 2: Gather Data
Run parallel queries for each available source:
- VCS State - branch/stack structure, recent commits, working dir status
- Code Review - open PRs, CI status, review decisions, activity
- Issues - recently updated, status, priority, assignments
- CI/CD - pipeline runs, success/failure, error summaries
Skip unavailable sources gracefully.
Stage 3: Aggregate
Cross-reference and organize:
- Group PRs by stack position (if stack-aware)
- Filter all by time constraint
- Correlate issues with PRs/branches
- Identify blockers (failed CI, blocking reviews)
- Calculate relative timestamps
Stage 4: Present
Format for scanning:
- Hierarchical sections (VCS -> PRs -> Issues -> CI)
- Visual indicators (
✓✗⏳for status) - Relative timestamps for recency
- Highlight attention-needed items
- Include links for deep-dive
See templates.md for section formats.
<data_sources>
VCS - stack visualization, commit history, working dir state
- Stack-aware (Graphite, git-stack): hierarchical branch relationships
- Standard git: branch, log, remote tracking
Code Review - PRs/MRs, CI checks, reviews, comments
- Platforms: GitHub, GitLab, Bitbucket, Gerrit
Issues - recent updates, metadata, repo relationships
- Platforms: Linear, Jira, GitHub Issues, GitLab Issues
CI/CD - runs, success/failure, timing, errors
- Platforms: GitHub Actions, GitLab CI, CircleCI, Jenkins
Tool-specific: graphite.md, github.md, linear.md, beads.md
</data_sources>
Cross-Referencing:
- PRs to branches (by name)
- Issues to PRs (by ID in title/body)
- CI runs to PRs (by number/SHA)
- Issues to repos (by reference)
Stack-Aware Organization:
- Group PRs by hierarchy
- Show parent/child relationships
- Indicate current position
- Highlight blockers in stack order
Filtering:
- Time: apply to all sources, use most recent update
- Status: prioritize action-needed, open before closed
Relative Timestamps:
- < 1 hour: "X minutes ago"
- < 24 hours: "X hours ago"
- < 7 days: "X days ago"
- = 7 days: "X weeks ago" or absolute
Visual Indicators:
✓success |✗failure |⏳pending |⏸draft |🔴blocker▓▓▓░░progress (3/5)◇minor |◆moderate |◆◆severe
Output Structure:
=== STATUS REPORT: {repo} ===
Generated: {timestamp}
{Time filter if applicable}
{VCS_SECTION}
{PR_SECTION}
{ISSUE_SECTION}
{CI_SECTION}
⚠️ ATTENTION NEEDED
{blockers and action items}See templates.md for detailed section templates.
Use scripts/sitrep.ts for automated gathering:
./scripts/sitrep.ts # All sources, 24h default
./scripts/sitrep.ts -t 7d # Last 7 days
./scripts/sitrep.ts -s github # Specific sources
./scripts/sitrep.ts --format=textOutputs JSON (structured) or text (human-readable). Reduces agent tool calls 80%+.
See implementation.md for script structure and patterns.
Required: VCS tool (git, gt, jj), shell access
Optional (graceful degradation):
- Code review CLI (gh, glab)
- Issue tracker MCP/API
- CI/CD platform API
Works with ANY available subset.
ALWAYS:
- Parse time constraints before queries
- Execute queries in parallel
- Handle missing sources gracefully
- Use relative timestamps
- Highlight actionable items
- Provide links for deep-dive
- Format for scanning
NEVER:
- Fail entirely if one source unavailable
- Block on slow queries (use timeouts)
- Expose credentials
- Dump raw data without organization
As session starter:
- Generate report (understand state)
- Identify attention-needed items
- Plan work (prioritize by blockers)
- Return periodically (track progress)
Cross-skill references:
- Failing CI -> debugging
- Before planning -> use report for context
- When blocked -> check dependencies
Automation: daily standup, pre-commit hooks, PR creation context
Tool integrations:
- graphite.md - Graphite stack and PR queries
- github.md - GitHub CLI patterns
- linear.md - Linear MCP integration
- beads.md - Local issue tracking
Implementation:
- templates.md - Output templates and formatting
- implementation.md - Patterns, scripts, anti-patterns
Examples:
- EXAMPLES.md - Usage examples and sample output
Formatting: