engram-issue-creation

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

Use this skill when:
- Creating a GitHub issue (bug report, feature request, docs improvement, or tracked question)
- Helping a contributor file an issue
- Triaging or approving issues as a maintainer

---

## Critical Rules

The [contribution policy transition](../../docs/contribution-policy-transition.md) is **PRE-CUTOVER / NOT ACTIVE**; the active rules below still apply.

1. **Blank issues are disabled** — MUST use the matching bug, feature, docs, or tracked-question template
2. **Every issue gets `status:needs-review` automatically** on creation
3. **`status:approved` means maintainer-accepted proportional evidence** as defined in CONTRIBUTING.md; bugs include current-main reproduction and root cause
4. **General questions go to [Discussions](https://github.com/Gentleman-Programming/engram/discussions)**; questions requiring tracked work use `type:question`

---

## Workflow

```
1. Search for a canonical root-cause tracker; add a new occurrence there when applicable
2. Choose the correct template and report consequence plus release context, not root cause or implementation
3. Submit → issue gets status:needs-review automatically
4. A maintainer triages and assigns an investigator, who records each same-root occurrence on the canonical tracker before duplicate closure
5. Use proportional evidence: scope/checks for trivial changes; current-remote-main SHA, reproduction, violated invariant/root cause, and regression test plan for bugs; approved design/non-goals and independent review plan for high-risk changes
6. A maintainer replaces the current status with status:approved after accepting that evidence; any real assignee satisfies ownership, not necessarily the PR author
```

---

## Issue Templates

### Bug Report

Template: `.github/ISSUE_TEMPLATE/bug_report.yml`
Auto-labels: `type:bug`, `status:needs-review`

#### Required Fields

| Field | Description |
|-------|-------------|
| **Existing Issue Search** | Required acknowledgement; add evidence to a canonical tracker when applicable |
| **Observed Consequence** | Clear user-visible consequence, without root-cause diagnosis |
| **Steps to Reproduce** | Numbered steps to reproduce |
| **Expected Behavior** | What should have happened |
| **Actual Behavior** | What happened instead (include errors/logs) |
| **Operating System** | Dropdown: macOS, Linux variants, Windows, WSL |
| **Release Version** | Report context from `engram version`; an investigator verifies current remote main |
| **Agent / Client** | Dropdown: Claude Code, OpenCode, Gemini CLI, Cursor, Windsurf, Other |

#### Optional Fields

| Field | Description |
|-------|-------------|
| **Relevant Logs** | Log output (auto-formatted as code block) |
| **Additional Context** | Screenshots, workarounds, extra info |

#### Example — Bug Report via CLI

```bash
gh issue create --template "bug_report.yml" \
  --title "fix(store): duplicate observations on concurrent saves" \
  --body "
### Observed Consequence
When two agents save observations concurrently, duplicates are created.

### Steps to Reproduce
1. Start two engram instances pointing to the same DB
2. Both save an observation with the same title simultaneously
3. Query observations — duplicates appear

### Expected Behavior
The second save should upsert, not insert a duplicate.

### Actual Behavior
Two identical observations exist with different IDs.

### Operating System
macOS

### Release Version
0.3.1

### Agent / Client
Claude Code

### Relevant Logs
\`\`\`
UNIQUE constraint failed: observations.title
\`\`\`
"
```

---

### Feature Request

Template: `.github/ISSUE_TEMPLATE/feature_request.yml`
Auto-labels: `type:feature`, `status:needs-review`

#### Required Fields

| Field | Description |
|-------|-------------|
| **Existing Issue Search** | Required acknowledgement; add evidence to a canonical tracker when applicable |
| **Observed Consequence** | User problem and impact, not an implementation proposal |
| **Desired Outcome** | User outcome, not an implementation proposal |
| **Affected Area** | Dropdown: CLI, MCP Server, TUI, Store, Sync, Skills, Documentation, Other |
| **Release Context** | Required report context; use `not release-specific` when applicable |

#### Optional Fields

| Field | Description |
|-------|-------------|
| **Workarounds and Constraints** | User-observed workarounds or constraints, not implementation alternatives |
| **Additional Context** | Mockups, examples, references |

From Gentleman-Programming/engram, Apache-2.0.

More from Gentleman-Programming/engram