engram-issue-creation
Issue creation workflow for Engram following the issue-first enforcement system. Trigger: When creating a GitHub issue, reporting a bug, or requesting a feature.
How do I install this agent skill?
npx skills add https://github.com/gentleman-programming/engram --skill engram-issue-creationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a standard workflow and command templates for creating and managing GitHub issues for the Engram project using the GitHub CLI. No security issues were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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-reviewautomatically on creation status:approvedmeans maintainer-accepted proportional evidence as defined in CONTRIBUTING.md; bugs include current-main reproduction and root cause- General questions go to 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 | 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
# 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"
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/gentleman-programming/engram/engram-issue-creation">View engram-issue-creation on skillZs</a>