Decision Framework

At a glance

• Purpose: Make consistent, explainable maintainer decisions (close/defer/ask/implement).
• Use when: You are about to recommend an action on an issue/PR, especially closing/declining/deferring.
• Gate: Before closure/deferral recommendations, load this file.
• Output: A decision + rationale + (if public) a draft response for approval.

Maintainer Intent

Act as a steward who wants the project to succeed. Beyond triage, seek high‑leverage improvements (docs, onboarding, examples, releases, tests, CI, API ergonomics). Apply CEV-style stewardship: optimize for what the project would want with better information and reflection.

Issue Decisions

Close Without Action

• Duplicate of existing issue (link to original)
• Support request better suited for discussions/Discord
• Feature explicitly out of scope per context.md
• Stale >90 days with no response to info request
• Already resolved by maintainer fix or release
• Cannot reproduce and reporter unresponsive

Request More Information

• Bug without reproduction steps
• Environment-specific issue without details
• Vague feature request
• Unclear expected vs actual behavior

Defer (Label + Acknowledge)

• Good idea but not current priority
• Needs design discussion first
• Blocked by external dependency
• Resource constrained

Prioritize for Work

• Blocking users (security, crash, data loss)
• High engagement (reactions, comments)
• Aligns with current priorities in context.md
• Quick win with clear path

PR Decisions

PRs are intelligence sources, not merge candidates. Extract insights and implement fixes yourself.

Extract and Implement

When a PR addresses a real problem:

1. Read the PR code to understand the fix approach
2. Identify the root cause they diagnosed
3. Note edge cases and test scenarios they considered
4. Implement your own fix using their insights
5. Close the PR with thanks and explanation

Close Directly

• Addresses issue already fixed
• Out of scope for project
• Fundamentally wrong approach
• Author unresponsive >30 days

When closing:

• Thank the contributor for identifying the problem
• Explain you've implemented a fix based on their insights (if applicable)
• Link to your commit/PR that addresses it

Defer Analysis

• Large change needs design discussion first
• Blocked by another decision
• Needs domain expertise to evaluate

Priority Scoring

Weights are defined in .github/maintainer/config.json. Use label boosts to reflect priorities and project focus. Defaults are in references/config.md.

Opportunity Decisions

Use these when no issue/PR explicitly asks for the work:

• Docs/UX win: Clear gap in README, examples, or API docs that reduces user friction
• Hygiene win: Tests, tooling, CI, or release processes that reduce future maintenance cost
• Adoption win: Small improvements that increase trust (badges, quickstarts, error messaging)

Capture these as briefs and include them in the prioritized queue.

Actionability States

| State | Meaning | Agent Action | |-------|---------|--------------| | ready | Can act now | Work on it | | needs-info | Waiting for reporter | Follow up or wait | | needs-decision | Requires maintainer judgment | Present to human | | needs-analysis | PR/issue needs intent extraction | Analyze and extract insights | | blocked | External dependency | Track, can't act | | stale | No activity, may be abandoned | Apply stale policy | | closable | Ready to close | Close with reason |

Actionability labels organize the queue; they do not imply skipping analysis.

Implementation Readiness Signals (PRs)

Use these signals together when deciding if a PR is a strong implementation candidate:

• Linked high-priority issues
• Relationship quality between issue intent and PR approach
• Clear intent and scope in description and comments
• Positive community reactions and sentiment
• CI status and unresolved threads
• Evidence of tests or quality checks (files touched, comments, review notes)

Implementation score is auto-generated and then adjusted by the agent. Record the adjustment in .github/maintainer/notes/ with agent_score, agent_confidence, and agent_rationale, and update relationship_quality_final as needed.

Stale Policy

Default thresholds (customize in .github/maintainer/standing-rules.md and config.json):

| Condition | Threshold | Action | |-----------|-----------|--------| | Issue waiting on reporter | 30 days | Comment asking for update | | Issue waiting on reporter | 60 days | Close with "stale" note | | PR waiting on author | 30 days | Close with "stale" note | | Draft PR with no activity | 30 days | Comment asking about status |

Always allow reopening if the contributor returns.