agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/close-issue-properly/SKILL.md

close-issue-properly

Skill8 starsChanged 11 days agoApache-2.0View on GitHub

Close GitHub issues with proper evidence and audit-ready records. Use when completing work on a tracked issue, when PM says "close the issue", "mark complete", "wrap up #N" or "done with #N", or before ending a session with completed work. Updates description checkboxes and adds closing comment.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 11 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ensure GitHub issues are closed with proper evidence, updated descriptions, and audit-ready records.

    line 13
  2. Distinctive:

    Use this skill when:

    line 17
  3. Distinctive:

    Before closing ANY issue, confirm:

    line 27
  4. Distinctive:

    All acceptance criteria from gameplan met?

    line 45
  5. Distinctive:

    No discovered work left unfiled?

    line 47
  6. Distinctive:

    Every unchecked box must have an explanation: No unexplained unchecked boxes.

    line 76
  7. Distinctive:

    Update the issue description with all checkbox changes:

    line 82
  8. Very specific:

    All completed checkboxes: [ ] → [x]

    line 101
  9. Very specific:

    Add status banner at the top if not present: Status: ✅ COMPLETE — [one-line summary], or for a superseded / won't-fix issue Status: ⚫ …

    line 102
  10. Distinctive:

    Add deferred items table if any items were skipped

    line 104
  11. Distinctive:

    Update any completion matrices with evidence links

    line 105
  12. Very specific:

    If issue closure involved bug investigation, also consider the Investigation Family (006/041-043/060).

    line 160
  13. Distinctive:

    Instead: File remaining work as issues, get PM guidance, or complete the work.

    line 187
  14. Distinctive:

    If the audit is actively being completed (boxes individually checked with evidence), use Examples 1–3 instead — superseded close is for the …

    line 355

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

close-issue-properly

Ensure GitHub issues are closed with proper evidence, updated descriptions, and audit-ready records.

When to Use

Use this skill when:

  • You've completed work on a tracked GitHub issue
  • PM asks you to "close the issue" or "mark complete"
  • You're wrapping up a session with open issues
  • A recurring auto-generated audit issue (e.g., FLY-AUDIT weekly docs audit) needs to be closed — completed or superseded; the discipline applies either way (see Example 5)

Pre-Flight Checklist (VERIFY BEFORE STARTING)

CRITICAL: The #1 failure mode is skipping the description update and only adding a comment. This leaves unchecked boxes that make the issue look incomplete forever.

Before closing ANY issue, confirm:

  • I have read the full issue description (gh issue view <id>)
  • I have identified ALL checkboxes that need updating
  • I will update the description FIRST, comment SECOND

Key Principle: The description is the permanent record. Comments are supplementary. An issue with unchecked boxes looks incomplete regardless of comments.

Procedure

Step 1: Pre-Close Validation

For epics (check children first):

gh issue view <issue-id>   # read its task list / sub-issues
# ALL children must be closed before closing epic

For all issues (verify completion):

  • All acceptance criteria from gameplan met?
  • Tests passing?
  • No discovered work left unfiled?

Stop if: Tests failing, criteria unmet, or open children exist.

Step 2: Analyze the Description (MANDATORY)

DO NOT SKIP THIS STEP. This is where most closure failures happen.

# Get the full issue body
gh issue view <id> --json body -q '.body' > /tmp/issue-body.md

# Review the body and identify:
# 1. Every [ ] checkbox
# 2. Any status fields
# 3. Any completion matrices

For each checkbox, determine its status (the one convention; close-issue was merged into this skill 2026-10-12):

SituationCheckbox becomesNote
Done, verified[x]none
Done, verified another way than the box implies[x][x] Item - *Verified: [how]*
Deferred to a follow-up issue[ ][ ] Item - *Deferred → #N: [reason]*
Not applicable / out of scope[ ][ ] Item - *N/A: [reason]*
Won't do[ ][ ] Item - *Won't do: [reason]*
Superseded (whole issue replaced or its window passed)[x][x] Item - *N/A:superseded* (see Example 5)

Every unchecked box must have an explanation. No unexplained unchecked boxes.

Step 3: Update Issue Description (BEFORE COMMENTING)

WARNING: If you skip to Step 4 without doing this, you've created a Comment-Only Close anti-pattern.

Update the issue description with all checkbox changes:

For simple issues (few checkboxes):

gh issue edit <id> --body "$(cat <<'EOF'
[Full updated body with [x] checkboxes and status changes]
EOF
)"

For complex issues (many checkboxes):

# Save updated body to file
gh issue view <id> --json body -q '.body' > /tmp/issue-body.md
# Edit /tmp/issue-body.md with all updates
gh issue edit <id> --body-file /tmp/issue-body.md

What to update:

  1. All completed checkboxes: [ ] → [x]
  2. Add status banner at the top if not present: **Status**: ✅ COMPLETE — [one-line summary], or for a superseded / won't-fix issue **Status**: ⚫ CLOSED — [superseded by #N / won't fix: reason]
  3. Add deferred items table if any items were skipped
  4. Update any completion matrices with evidence links

Step 4: Add Closing Comment

Only after Step 3 is complete, add a comment with implementation evidence:

gh issue comment <id> --body "$(cat <<'EOF'
## Implementation Complete

### Summary
[1-2 sentence summary of what was done]

### Changes Made
- [File]: [What changed]
- [File]: [What changed]

### Verification
- **Verified how**: [REQUIRED — the method actually run this time (command/probe), the layer it
  measured (m-43: curl 200 ≠ render test), and the denominator (m-44: covered X of Y). A closure
  without this line is an unverified claim — per CLAUDE.md §Evidence Required, 2026-08-29.]
- Evidence doc: [path if applicable]
- Tests: [count] passing (if applicable)
- Files modified: [list]

### Deferred Items (if any)
| Item | Reason |
|------|--------|
| [Item] | [Why deferred] |
EOF
)"

Step 5: Close the Issue

gh issue close <id>
# superseded, won't-do or window-passed:
gh issue close <id> --reason "not planned"

Step 6: Tell the parent epic (if any)

gh issue comment <epic-id> --body "Child closed: #<id> ([title]) ✅"

Pattern Families

This skill applies patterns from the Completion Theater Family (045/046/047/049):

  • Pattern-045: Diagnoses gap between "tests pass" and "users succeed" — verify real completion
  • Pattern-046: Enforces 100% completion criteria — no rationalizing gaps as "minor"
  • Pattern-049: Audit at phase boundaries — closing an issue is a phase boundary

If issue closure involved bug investigation, also consider the Investigation Family (006/041-043/060).

See PATTERN-FAMILIES.md for full family index.


Anti-Patterns to Avoid

Anti-PatternWhy It's BadCorrect Approach
Comment-Only CloseDescription still shows unchecked boxes; looks incomplete foreverUpdate description FIRST, then comment
Close with failing testsIncomplete work marked doneFile P0 blocker, keep open
Close epic with open childrenWork disappears from trackingComplete children or get PM approval
Skip the evidenceCan't verify laterInclude test output, commits
Rationalize gaps as "minor"Expedience over disciplineComplete all criteria or escalate
Unexplained unchecked boxesFuture readers can't tell if skipped or forgottenAdd note to every unchecked box

Stop Conditions

DO NOT close the issue if:

  1. Tests are failing
  2. Epic has open children without PM approval
  3. Acceptance criteria are not met
  4. You cannot provide verification evidence
  5. You're rationalizing incomplete work as "good enough"
  6. You haven't updated the description checkboxes

Instead: File remaining work as issues, get PM guidance, or complete the work.

Quality Checklist (Final Verification)

Before closing, verify:

  • Description updated with all checkboxes marked appropriately
  • No unexplained unchecked boxes - every [ ] has a note
  • Status banner shows COMPLETE
  • Closing comment added with evidence template
  • Tests passing (if applicable)
  • If epic: all children closed
  • If a child: parent epic told

Examples

Example 1: Standard Task Closure (Full Flow)

# Step 1: Verify work complete
pytest tests/unit/test_feature.py -v  # 5 passed

# Step 2: Analyze description
gh issue view 543 --json body -q '.body' > /tmp/issue-543.md
cat /tmp/issue-543.md  # Review all checkboxes

# Step 3: Update description (the critical step!)
# Edit /tmp/issue-543.md:
#   - Change [ ] to [x] for completed items
#   - Add "**Status**: ✅ COMPLETE" at top
#   - Add notes to any unchecked items
gh issue edit 543 --body-file /tmp/issue-543.md

# Step 4: Add closing comment
gh issue comment 543 --body "## Implementation Complete

### Summary
Added input validation to user handler.

### Verification
- Commit: a1b2c3d
- Tests: 5 passing
- Files: services/handlers/input.py, tests/unit/test_input.py"

# Step 5: Close
gh issue close 543

Example 2: Issue with Deferred Items

# After updating description with:
#   [x] Implement core feature
#   [x] Add unit tests
#   [ ] Update documentation - *Deferred: will address in #567*
#   [ ] Performance optimization - *N/A: not needed for MVP*

gh issue comment 543 --body "## Implementation Complete

### Summary
Core feature implemented with tests. Documentation deferred to #567.

### Verification
- Commit: a1b2c3d
- Tests: 8 passing

### Deferred Items
| Item | Reason |
|------|--------|
| Update documentation | Separate issue #567 |
| Performance optimization | Not needed for MVP scope |"

gh issue close 543

Example 3: Epic Closure

# Step 1: Check all children closed
gh issue view 42   # read the epic's task list / sub-issues
# Shows: 3/3 children closed

# Step 2-3: Update epic description with summary of children
gh issue view epic-42 --json body -q '.body' > /tmp/epic-42.md
# Edit to mark all child references as [x] complete
gh issue edit epic-42 --body-file /tmp/epic-42.md

# Step 4: Add closing comment summarizing children
gh issue comment epic-42 --body "## Epic Complete

### Children Completed
- #43: Feature A ✅
- #44: Feature B ✅
- #45: Feature C ✅

### Verification
All 3 child issues closed with evidence."

# Step 5: Close epic
gh issue close epic-42

Example 4: Blocked - Cannot Close

# Tests failing - DO NOT CLOSE
pytest tests/  # 2 failed

# Instead:
# 1. File P0 blocker issue for failing tests
gh issue create --title "P0: Fix failing tests in feature X" --label blocker --body "<details> Blocks #<original-issue>."

# 2. Keep original issue open
# 3. Report to PM

Example 5: Recurring auto-generated audit (close-as-superseded)

Some issues are filed automatically each week or month by github-actions (e.g., FLY-AUDIT weekly docs audit). They land with 50–100 checklist items spanning many areas. Typical outcome: nobody runs all the items, the issue sits open with all-unchecked boxes, and the next week's audit lands while the previous one is still orphaned.

The close-properly discipline still applies — and the natural close-reason for these is superseded by the next scheduled audit. Default cadence: close within ~7–14 days of creation, ideally before the next audit lands.

# 1. Verify the recurrence + find the successor (the next-week audit)
gh issue list --label fly-audit --state all --limit 5

# 2. Fetch current body
gh issue view <id> --json body | python3 -c "
import json, sys
body = json.load(sys.stdin)['body']

banner = '''## ⚪ STATUS: Closed as superseded — <date>

This weekly audit was not completed at the time. Subsequent weekly audits #<next-id> (<date>) supersede this audit window.

Per close-issue-properly skill discipline: marking all checklist items as N/A:superseded (boxes checked to signal addressed-via-supersession). Closing reason: not planned (window has passed; no retroactive value).

---

'''

new = banner + body.replace('- [ ]', '- [x] *N/A:superseded*')
open('/tmp/issue-body.md', 'w').write(new)
"

# 3. Apply description update FIRST
gh issue edit <id> --body-file /tmp/issue-body.md

# 4. Closing comment
gh issue comment <id> --body "
Closing as superseded per close-issue-properly skill.

Subsequent audits cover this window:
- #<next-id> (<title>) — closed <date>

Description body updated with status banner + all N checkboxes marked
\`[x] *N/A:superseded*\` (addressed-via-supersession). Closing via
\`--reason 'not planned'\`.
"

# 5. Close
gh issue close <id> --reason "not planned"

Discipline notes:

  • The body update still happens first — same Comment-Only-Close anti-pattern applies. A recurring audit closed with 95 unchecked boxes still looks orphan-forever.
  • Don't backfill old audit content — the items in the audit have already missed their window; running them retroactively is sunk-cost. Mark N/A:superseded rather than executing them out of cycle.
  • Monday-morning sweep (optional): a designated agent (Docs lane is natural) can close the previous week's audit before the new one auto-generates, so the recurring series never accumulates orphans. Today's issue and its successor both get processed cleanly.
  • If the audit is actively being completed (boxes individually checked with evidence), use Examples 1–3 instead — superseded close is for the no-work-was-done case.

May 17 evidence: #1049 (FLY-AUDIT 2026-05-04) was sitting open with 95 unchecked boxes 13 days post-creation; #1076 (FLY-AUDIT 2026-05-11) had been closed similarly orphaned the prior week. This example codifies the close-as-superseded pattern to prevent both classes of orphan.


Changelog

  • v1.3 (2026-10-12): Merged close-issue (v1.0, the generalized copy) into this skill on xian's D-D "yes" (R6 defect C17, relayed by Exec 10-12). Brought over its checkbox-status table (Won't do, Verified-another-way, Deferred → #N), the ⚫ CLOSED banner for superseded/won't-fix issues, the parent-epic step and its trigger phrases. Removed the Beads (bd, bd-safe, bd sync) steps: Beads isn't installed on Amber and GitHub is the tracker (CIO ruling 2026-10-05). close-issue deleted; its references now point here.
  • v1.2 (2026-05-17): Added Example 5 (Recurring auto-generated audit — close-as-superseded). Codifies the close-as-superseded pattern for FLY-AUDIT-style recurring issues so they don't accumulate as orphans with 95 unchecked boxes. May 17 trigger: #1049 sat 13 days post-creation; #1076 was previously closed with all-unchecked. Optional Monday-morning sweep noted as preventive practice.
  • v1.1 (2026-02-09): Added Pre-Flight Checklist, expanded Step 2 with mandatory analysis, added warnings about Comment-Only Close anti-pattern, improved examples with full flow
  • v1.0 (2026-01-21): Initial version

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.