engram-backlog-triage

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

Use this skill when:
- Running a full backlog audit on Engram (or any repo)
- Deciding merge / request-changes / close / needs-design / approve-issue
- Cleaning noise from the issue tracker
- Prioritizing what to act on next

---

## Maintainer Philosophy (Engram)

These are the non-negotiable product values. Every triage decision is filtered through them.

| Principle | What it means in practice |
|-----------|--------------------------|
| **Zero-config** | Works out of the box. No required flags, env vars, or setup beyond install. |
| **Local-first** | Data lives in `~/.engram/engram.db`. No cloud dependency by default. |
| **Single binary** | One `engram` binary. No daemon, no service, no secondary processes needed. |
| **Terminal-first** | CLI and TUI are the primary UX. No web dashboard, no Electron. |
| **Thin adapters** | Plugin scripts (Claude, OpenCode, Gemini, Codex) are thin shims — logic lives in Go core. |
| **Issue-first** | Every PR must link a `status:approved` issue. No approved issue → no PR. |
| **Evidence-based reviews** | Request changes with specific, actionable items. No vague "needs improvement". |
| **Tight scope** | Reject features that expand Engram's surface area without a compelling case. |
| **Small focused contributions** | Prefer 50-line PRs solving one problem over 500-line PRs solving five. |
| **Reject vague/scope-breaking work** | Close scope-creep issues and PRs that turn Engram into something else. |

---

## Disposition Classification

Assign exactly ONE disposition to each issue or PR:

| Disposition | When to use |
|-------------|-------------|
| **MERGE** | PR is correct, scoped, tests pass, linked approved issue. Merge immediately. |
| **REQUEST CHANGES** | PR has the right idea but needs specific fixes. List each item. |
| **CLOSE** | Noise, confirmed duplicate, vague/scope-breaking work, or obsolete work after maintainer review; missing approval/ownership alone requires remediation before merge. |
| **NEEDS DESIGN** | Idea is valid but architectural decision required before any PR is welcome. Open discussion or design issue first. |
| **APPROVE ISSUE** | Maintainer accepted proportional evidence per CONTRIBUTING.md; bugs include current-main SHA, reproduction, root cause, and regression test plan. Replace the current status with `status:approved`. |
| **REJECT ISSUE** | Vague, duplicate, scope-breaking, or belongs in Discussions. Close with explanation. |

---

## Operating Phases

### Phase 1 — Fetch the Backlog

```bash
# All open issues with labels and comments
gh issue list --repo <owner/repo> --state open \
  --json number,title,labels,author,comments,body \
  --limit 100

# All open PRs with labels and review state
gh pr list --repo <owner/repo> --state open \
  --json number,title,labels,author,body,reviews,commits \
  --limit 50

# Check a specific issue in detail
gh issue view <number> --repo <owner/repo> --json number,title,body,labels,comments

# Check a specific PR in detail
gh pr view <number> --repo <owner/repo> --json number,title,body,labels,files,reviews
```

### Phase 2 — Classify Each Item

For every issue, answer:

```
1. Search for a canonical root-cause tracker; use `status:possible-duplicate` only while evaluating
2. Assign an investigator; for bugs, reproduce against exact current remote `main` and record SHA
3. For bugs, identify the first violated repository-owned invariant; cluster only same-root/contract reports
4. Accept scope/checks for trivial changes; reproduction/root/regression plan for bugs; approved design/non-goals and independent review plan for high-risk changes
5. Is it vague, a general question, or a discussion? → REJECT ISSUE (redirect general questions and support to Discussions; retain tracked questions requiring maintainer investigation, a repository change, or a durable decision)
6. Does it break zero-config / local-first / single-binary? → REJECT ISSUE
7. Confirmed duplicate? Move useful evidence to canonical, then close not planned with `status:wontfix` + `resolution:duplicate`
```

For every PR, answer:

```
1. Is every linked issue status:approved and assigned to a real owner? → if not → REQUEST CHANGES before merge
2. Does it have exactly one type:* label? → if not → REQUEST CHANGES
3. Do all six required contexts pass? → if not → REQUEST CHANGES (list failures)
4. Is the scope tight (one issue, minimal diff)? → if sprawling → REQUEST CHANGES
5. Does it follow conventional commits + branch naming? → if not → REQUEST CHANGES
6. Is the change correct and well-tested? → if yes → MERGE
```

Existing PRs must comply before merge; activating the gate does not require completing the whole backlog first. Reconcile approval/ownership as PRs become active or approach merge, re-run native validation after issue changes, and never assign placeholders to satisfy CI. Evidence can live in the issue; no separate design document is required by default.

### Phase 3 — Infer Ideology from Maintainer Comments

Look for maintainer responses (MEMBER or OWNER association) in issue comments. Extract:

- What the maintainer approved and how they framed it
- What the maintainer redirected (Questions → Discussions, etc.)
- What the maintainer scoped down ("Best place for it: add a section in DOCS.md")
- What the maintainer welcomed vs deferred ("I'll keep this issue open to track that")

Use these patterns to calibrate your triage against the actual maintainer stance, not just the written philosophy.

```bash
# Filter for maintainer responses
gh issue view <number> --repo <owner/repo> --json comments \
  --jq '.comments[] | select(.authorAssociation == "MEMBER" or .authorAssociation == "OWNER") | {author: .author.login, body: .body}'
```

### Phase 4 — Prioritize

Rank items within each disposition bucket:

**Quick wins (act immediately):**
- Real bugs with clear reproduction steps + no linked PR yet
- PRs that are correct, scoped, and just need a label or minor fix
- Docs PRs that are accurate and unambiguous

From Gentleman-Programming/engram, Apache-2.0.

More from Gentleman-Programming/engram