Skill v1.0.2
currentAutomated scan100/100+1 new
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 is PRE-CUTOVER / NOT ACTIVE; the active rules below still apply.
- Blank issues are disabled — MUST use the matching bug, feature, docs, or tracked-question template
- Every issue gets `status:needs-review` automatically on creation
- `status:approved` means maintainer-accepted proportional evidence as defined in CONTRIBUTING.md; bugs include current-main reproduction and root cause
- 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 applicable2. Choose the correct template and report consequence plus release context, not root cause or implementation3. Submit → issue gets status:needs-review automatically4. A maintainer triages and assigns an investigator, who records each same-root occurrence on the canonical tracker before duplicate closure5. 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 changes6. 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 ConsequenceWhen two agents save observations concurrently, duplicates are created.### Steps to Reproduce1. Start two engram instances pointing to the same DB2. Both save an observation with the same title simultaneously3. Query observations — duplicates appear### Expected BehaviorThe second save should upsert, not insert a duplicate.### Actual BehaviorTwo identical observations exist with different IDs.### Operating SystemmacOS### Release Version0.3.1### Agent / ClientClaude 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 ConsequenceWhen scripting with engram, parsing human-readable search results is fragile.### Desired OutcomeScripts can consume search results without parsing human-readable output.### Release Contextnot release-specific### Affected AreaCLI (commands, flags)### Workarounds and ConstraintsUsing \`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 | type:feature, status:needs-review | |
| Documentation Improvement | type:docs, status:needs-review | |
| Tracked Question | type:question, status:needs-review |
Applied by Maintainers
| Label | When to apply | |
|---|---|---|
status:approved | Proportional evidence accepted; bugs include current-main reproduction and root-cause evidence | |
priority:critical | Critical bug or urgent feature | |
priority:high | High priority | |
priority:medium | Important but not blocking | |
priority:low | Nice to have | |
status:possible-duplicate | Duplicate under evaluation | |
status:wontfix | Closed without implementation, including confirmed duplicates | |
resolution:duplicate | Confirmed duplicate after closure |
Maintainer Approval Workflow
1. Search for a canonical tracker, triage the consequence, and assign an investigator2. For bugs, reproduce against exact current remote main and record SHA; identify the first violated repository-owned invariant3. Cluster only same-root/contract occurrences; keep distinct roots separate4. Accept evidence proportional to risk using CONTRIBUTING.md; a short issue explanation suffices, no separate design document by default5. If accepted → replace the current status with status:approved; otherwise explain and close if needed6. Require approval and a real assignee for new implementation; existing PRs must comply before merge, not before backlog-wide activation
Decision Tree
Is it a bug? → Use Bug Report templateIs it a new feature/improvement? → Use Feature Request templateIs it a general question? → Use Discussions, NOT issuesIs it a tracked question? → Use the Tracked Question templateIs it a possible duplicate? → Replace the current status with status:possible-duplicateIs it a confirmed duplicate? → Close it, replace evaluation status with status:wontfix, then add resolution:duplicate
Commands
# Search existing issues before creating to keep canonical evidence togethergh issue list --search "keyword"# Create bug reportgh issue create --template "bug_report.yml" --title "fix(scope): description"# Create feature requestgh issue create --template "feature_request.yml" --title "feat(scope): description"# Create documentation improvementgh issue create --template "docs_improvement.yml" --title "docs(scope): description"# Create tracked questiongh issue create --template "tracked_question.yml" --title "question(scope): description"# Maintainer: approve an issuegh issue edit <number> --remove-label "status:needs-review" --add-label "status:approved"# Maintainer: add prioritygh issue edit <number> --add-label "priority:high"# Maintainer: replace every active status while evaluating a possible duplicateset -euo pipefailother_statuses="$(gh issue view <number> --json labels --jq '.labels[].name | select(startswith("status:") and . != "status:possible-duplicate")')"status_args=(--add-label "status:possible-duplicate")if [[ -n "$other_statuses" ]]; thenstatus_args+=(--remove-label "${other_statuses//$'\n'/,}")figh issue edit <number> "${status_args[@]}"updated_statuses="$(gh issue view <number> --json labels --jq '.labels[].name | select(startswith("status:"))')"if [[ "$updated_statuses" != "status:possible-duplicate" ]]; thenecho "status replacement could not be confirmed; stop without retrying" >&2exit 1fi# Maintainer: close a confirmed duplicate, then replace evaluation status with terminal status and resolutiongh issue close <number> --reason "not planned" --comment "Closing as duplicate of #<canonical>."gh issue edit <number> --remove-label "status:possible-duplicate" --add-label "status:wontfix,resolution:duplicate"