share-plan

name	share-plan
description	Use when sharing an implementation plan to a GitHub issue. Formats plans with collapsible details sections so issues are scannable but comprehensive.

Share Plan

Format an implementation plan into a GitHub issue using collapsible <details><summary> sections. The issue stays scannable at a glance while preserving full implementation depth for whoever picks it up.

Arguments

$ARGUMENTS

Instructions

1. Identify the Plan

Find the implementation plan from one of these sources (in priority order):

1. Explicit file path in arguments -- read it directly
2. Conversation context -- extract from the current session's discussion

If no plan is found, stop and tell the user.

2. Determine Target

• #NNN in arguments -- update that existing issue
• new in arguments -- create a new issue (derive title from plan context or remaining args)
• Neither -- ask whether to update an existing issue or create a new one

For existing issues: fetch the body with gh issue view NNN --json body,title. Preserve the Problem and Goal sections if they exist -- only add/replace implementation sections.

3. Format the Issue Body

Structure the updated issue body using this template:

## Problem

[Keep existing or write from plan context]

## Goal

[Keep existing or write from plan context]

## Approach

[High-level summary: 3-5 bullets max. What technology/pattern, why this approach,
key design decisions. This is the only section most readers will read.]

## Files to Create/Modify

| File           | Action      | Purpose          |
| -------------- | ----------- | ---------------- |
| `path/to/file` | Create/Edit | One-line purpose |

## Implementation

<details>
<summary>[Component or step name]</summary>

[Full implementation detail -- logic, pseudocode, config snippets, etc.]

</details>

<details>
<summary>[Another component]</summary>

[Details...]

</details>

<details>
<summary>Edge cases</summary>

[Known edge cases, limitations, things to verify during implementation]

</details>

## Notes

[Cross-references to related issues, links to plan files, etc. Optional.]

Formatting rules:

• Every <details> block needs a blank line after <summary> and before </details> for GitHub rendering
• Keep the Approach section above the fold -- no <details> wrapper
• Put code snippets, config examples, and step-by-step logic inside <details>
• Use the Files table as a quick-reference index
• Group implementation details by component, not by step number
• Edge cases always get their own <details> block

4. Publish

Write the formatted body to a temp file to avoid shell escaping issues with backticks and code fences. Commands will prompt for approval since they're not in allowed-tools.

# Write the formatted body (no shell escaping concerns)
cat > /tmp/plan-body.md << 'PLAN'
...formatted body...
PLAN

Update existing issue:

gh issue edit NNN --body-file /tmp/plan-body.md

Create new issue:

gh issue create --title "TITLE" --body-file /tmp/plan-body.md

What makes this work or fail

The point is an issue that reads in thirty seconds and still answers questions three weeks later. That breaks in two directions: burying the approach summary inside a <details> block so the scannable part is empty, or dumping raw plan prose so there's nothing to scan at all. Grouping by component rather than by step is what keeps the collapsed sections meaningful — a <details> per sentence is the same wall of text with more clicks.