engram-issue-creation

## 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 | #### Example — Feature Request via CLI ```bash 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 | `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 investigator 2. For bugs, reproduce against exact current remote main and record SHA; identify the first violated repository-owned invariant 3. Cluster only same-root/contract occurrences; keep distinct roots separate 4. Accept evidence proportional to risk using CONTRIBUTING.md; a short issue explanation suffices, no separate design document by default 5. If accepted → replace the current status with status:approved; otherwise explain and close if needed 6. 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 template Is it a new feature/improvement? → Use Feature Request template Is it a general question? → Use Discussions, NOT issues Is it a tracked question? → Use the Tracked Question template Is it a possible duplicate? → Replace the current status with status:possible-duplicate Is it a confirmed duplicate? → Close it, replace evaluation status with status:wontfix, then add resolution:duplicate ``` --- ## Commands ```bash # Search existing issues before creating to keep canonical evidence together gh issue list --search "keyword" # Create bug report gh issue create --template "bug_report.yml" --title "fix(scope): description" # Create feature request gh issue create --template "feature_request.yml" --title "feat(scope): description" # Create documentation improvement gh issue create --template "docs_improvement.yml" --title "docs(scope): description" # Create tracked question gh issue create --template "tracked_question.yml" --title "question(scope): description" # Maintainer: approve an issue gh issue edit <number> --remove-label "status:needs-review" --add-label "status:approved" # Maintainer: add priority gh issue edit <number> --add-label "priority:high" # Maintainer: replace every active status while evaluating a possible duplicate set -euo pipefail other_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" ]]; then status_args+=(--remove-label "${other_statuses//$'\n'/,}") fi gh 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" ]]; then echo "status replacement could not be confirmed; stop without retrying" >&2 exit 1 fi # Maintainer: close a confirmed duplicate, then replace evaluation status with terminal status and resolution gh 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" ```