Maintenance Workflow

At a glance

• Purpose: Deep, step-by-step workflow details behind the SKILL.md runbook.
• Use when: You’re uncertain what to do next, or need the exact stage outputs/approval points.
• Note: SKILL.md is the canonical runbook; this file is the deeper reference.

Core Philosophy: Agent-Implemented Fixes

PRs are intelligence sources, not merge candidates.

External PRs reveal:

• What problems exist
• How contributors attempted to solve them
• Edge cases and platform-specific issues

The agent's job is to:

1. Extract intent and insights from PRs
2. Understand the problem and approach
3. Implement the fix yourself using the PR as guidance
4. Thank contributors and close their PRs with explanation

Never merge external PRs directly. The agent writes all code.

Maintainer Mindset

Act as a project steward who wants the repo to succeed. In addition to fixes, look for:

• Documentation gaps and onboarding friction
• UX or API rough edges
• Maintenance hygiene (tests, tooling, CI, release notes)
• Small improvements that increase adoption and trust Apply CEV-style stewardship: optimize for what the project would want with better information and reflection, not just what is loudest.

Pre-requisites

The triage script automatically initializes .github/maintainer/ with template files on first run. After running, review and customize context.md with project-specific information. See repo-state-template.md for template details. The script also creates .github/maintainer/config.json with defaults if missing. See config.md. The agent maintains .github/maintainer/semantics.generated.json from templates/docs; do not edit manually. Persistent notes live in .github/maintainer/notes/ and are merged into each report.

Workflow Stages

Stage 0: Scope

• Confirm repo, date range, and scope (open items by default)
• Check .github/maintainer/context.md for project priorities and tone
• Determine approval policy (default: draft everything, ask before public actions)

Stage 1: Capture

Run triage script from repo root:

npx tsx path/to/triage.ts [--delta] [--datetime YYYY-MM-DDTHH-MM-SS] [--config path]

Flags:

• --delta: Compare with previous run, generate delta.md
• --datetime: Override timestamp (default: current datetime)
• --config: Override config path (default: .github/maintainer/config.json)

Outputs to <reportsDir>/YYYY-MM-DDTHH-MM-SS/ (default reports/).

Stage 2: Analyze

For each item:

1. Read item markdown (e.g., items/issues/ISSUE-42.md)
2. Extract intent using intent-extraction.md
3. Classify actionability (ready, needs-info, needs-decision, needs-analysis, blocked, stale, closable)
4. Score priority using config weights and label boosts from .github/maintainer/config.json
5. Review sentiment and relationship signals (PRs)
6. Map relationships to other items
7. Update item markdown with analysis
8. Update persistent note frontmatter for PRs (agent_score, agent_confidence, agent_rationale, relationship_quality_final)

Actionability is not a gate. Review every item. Use implementation score/tier to surface the best candidates.

Update triage.md with prioritized queue and agent-briefs.md with ready tasks. Draft per-task prompts in agent-prompts.md after synthesis.

Stage 3: Synthesize Opportunities

Create an explicit opportunity list (docs, onboarding, hygiene, UX, release tasks) and fold the highest-impact items into the prioritized queue.

Stage 4: Align

Present to human:

• Executive summary with actionability breakdown
• Top priorities with citations (e.g., [ISSUE:42])
• Proposed actions (close, respond, implement, defer) plus opportunity work
• Items needing human decision

Wait for explicit approval before public actions.

Stage 5: Execute

With approval:

• Implement fixes yourself using PR insights as guidance
• Draft responses thanking contributors
• Close PRs with explanation (agent implemented the fix)
• Close resolved issues with references
• Get approval before posting any public response

Stage 6: Record

Update per-repo state:

• Log decisions to .github/maintainer/decisions.md
• Update .github/maintainer/contributors.md with notes
• Record patterns in .github/maintainer/patterns.md
• Update state.json with run metadata

Delta Mode

When using --delta:

1. Script reads .github/maintainer/state.json to find last run
2. Compares current state with previous snapshot
3. Generates delta.md showing:
   • New items since last run
   • Updated items (new comments, status changes)
   • Closed items
   • Stale items (no activity threshold)

Focus analysis on delta items first, then review full backlog as needed.

Human-in-the-Loop Points

Never automate without approval:

• Posting comments
• Closing issues/PRs
• Rejecting contributions

Draft all public-facing content first, present for review.