/issue-creation

name: engram-issue-creation
description: >
  Issue creation workflow for Engram following the issue-first enforcement system.
  Trigger: When creating a GitHub issue, reporting a bug, or requesting a feature.
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "1.0"

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

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 |

Example — Feature Request via CLI

gh issue create --template "feature_request.yml" \
  --title "feat(cli): add --json flag to mem search" \
  --body "
### Observed Consequence
When scripting with engram, parsing human-readable search results is fragile.

### Desired Outcome
Scripts can consume search results without parsing human-readable output.

### Release Context
not release-specific

### Affected Area
CLI (commands, flags)

### Workarounds and Constraints
Using \`jq\` to parse the current output is unreliable because the format is unstructured.
"

---

Tracked Question

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

Use this form only when the answer requires maintainer investigation, a repository change, or a durable decision. Send general questions and support to Discussions.

Required fields: existing-issue search acknowledgement, question, tracking reason, affected area, and release context. Additional context is optional.

---

Label System

Applied Automatically on Issue Creation

| Template | Labels added | |----------|-------------| | Bug Report | `type:bug`, `status:needs-review` | | Feature Request | `ty