Skip to content

Include issue comments during /issue-init (#45) #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jepegit merged 1 commit into from
Apr 19, 2026
Merged

Include issue comments during /issue-init (#45) #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .issueflows/03-solved-issues/issue45_original.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Issue #45: include issue comments

Source: https://github.com/jepegit/issue-flow/issues/45

## Original issue text

It seems like issue-flow (during init) does not take into account additional comments to the issue. This is often not the wanted behaviour.

Task

1. improve "/issue-init" so that it also goes through the comments and include tasks from them (depending on the context, some comments might be downvoted or negated later on in the comment section). The comment section (added inside the _original.md file) does not have to be a 1-to-1 representation of the actual comments.
2. add another skill - describing how to review the comments and extract relevant tasks from them.
89 changes: 89 additions & 0 deletions .issueflows/03-solved-issues/issue45_plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Plan for issue #45: include issue comments

## Goal

Make `/issue-init` comment-aware: fetch GitHub issue comments along with the body, and append a curated summary section to `issue<N>_original.md` that distills follow-up tasks, clarifications, and superseded points. Ship a companion skill (`issueflow-issue-comments`) that the init command and future work can lean on when interpreting comment threads.

## Constraints

- Preserve the existing `## Original issue text` contract: the body is kept byte-for-byte as GitHub returns it. Comments go in a new, separate section so diffs of the original body stay clean.
- Both deliverables must render cleanly through `issue_flow.templating.render_template` (defaults: `{{ issueflows_dir }}`, `{{ agent_dir }}`, etc.).
- `TEMPLATE_MANIFEST` in [src/issue_flow/templating.py](src/issue_flow/templating.py) must list the new skill, and `tests/test_templating.py` expectations must stay green.
- Keep changes cohesive with the existing tone/structure of [commands/issue-init.md.j2](src/issue_flow/templates/commands/issue-init.md.j2) and [skills/issueflow_issue_init/SKILL.md.j2](src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2).
- No design/guide doc needed under `.issueflows/04-designs-and-guides/` for this change (behavior is fully captured in the command + skill templates).

## Approach

1. **Fetch shape.** Switch the `gh` call in the `/issue-init` spec from `--json title,body,url,number` to `--json title,body,url,number,comments`. That returns each comment with `author.login`, `body`, and `createdAt`, which is enough for curation.

2. **File layout inside `issue<N>_original.md`.** Add one new optional section after the original body. The body section is unchanged (still byte-for-byte). If the issue has no comments, omit the new section entirely. Template:

```markdown
# Issue #<number>: <title>

Source: <url>

## Original issue text

<body exactly as in GitHub issue>

## Comments (curated summary)

- **Additional tasks**: <bullets distilled from comments that add real work>
- **Clarifications / constraints**: <bullets the agent should honour>
- **Superseded / retracted**: <earlier points later contradicted or walked back>

_Note: this section is an interpretive summary, not a verbatim comment dump. Source comments: <count>, last comment by @<login> on <date>._
```

- The curated summary is produced by the agent at init time using the new skill.
- No verbatim paste of comments (per the issue: "does not have to be a 1-to-1 representation").

3. **Command edits** — [src/issue_flow/templates/commands/issue-init.md.j2](src/issue_flow/templates/commands/issue-init.md.j2):
- Step 2: fetch `title, body, url, number, comments`.
- New step 2a "Triage comments": call out the new skill `issueflow-issue-comments` as the playbook; list what counts as an additional task, a clarification, or a superseded point; explicitly allow collapsing/dropping noise.
- Step 5: extend the file-content format with the optional `## Comments (curated summary)` section, and state the "omit if no comments" rule.
- Constraints section: clarify that the body remains byte-for-byte; only the new section is interpretive.
- Output section: include "N comments triaged" in the summary to the user.

4. **Init skill edits** — [src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2](src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2):
- Mirror the fetch change and add a short "Triage comments" step right before the write step.
- Point to the new `issueflow-issue-comments` skill for the triage rules.
- Update the "Write" section to show the optional curated-comments block.

5. **New skill** — create `src/issue_flow/templates/skills/issueflow_issue_comments/SKILL.md.j2` with the standard frontmatter (`disable-model-invocation: true`, name `issueflow-issue-comments`) and sections:
- **When to use** — invoked by `/issue-init` (and reusable by any workflow that needs to re-triage comments later).
- **Inputs** — the JSON array of comments from `gh issue view --json comments` (author, body, createdAt).
- **Triage rules** — chronological precedence (later wins conflicts); explicit negations move earlier items into Superseded; collapse duplicates; ignore chit-chat, LGTMs, bot messages; three buckets (additional tasks / clarifications / superseded); paraphrase, quote sparingly.
- **Output contract** — the exact markdown block shown in step 2.
- **Edge cases** — zero comments (skip section), only bot comments (skip section), heated/multi-author threads (note the disagreement rather than guessing a winner).

6. **Manifest + tests** — [src/issue_flow/templating.py](src/issue_flow/templating.py):
- Add `("skills/issueflow_issue_comments/SKILL.md.j2", "{agent_dir}/skills/issueflow-issue-comments/SKILL.md")` to `TEMPLATE_MANIFEST`.
- [tests/test_templating.py](tests/test_templating.py):
- Bump `test_manifest_entry_count` from 20 to 21 and fix the inline comment.
- Add `issueflow_issue_comments` to the list in `test_manifest_has_expected_commands_and_skills`.
- Add `test_issue_init_fetches_and_triages_comments` asserting the rendered `issue-init` command mentions comments fetching, the curated-summary section header, and the new skill name.
- Add `test_issue_comments_skill_documents_triage_rules` asserting the new skill renders, mentions chronological precedence and the three buckets.

## Files to touch

- [src/issue_flow/templates/commands/issue-init.md.j2](src/issue_flow/templates/commands/issue-init.md.j2) — fetch comments, add triage step, extend file-content format, update constraints + output.
- [src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2](src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2) — mirror the command changes; point at the new skill.
- `src/issue_flow/templates/skills/issueflow_issue_comments/SKILL.md.j2` (new) — full triage skill.
- [src/issue_flow/templating.py](src/issue_flow/templating.py) — register the new skill in `TEMPLATE_MANIFEST`.
- [tests/test_templating.py](tests/test_templating.py) — bump count, extend lists, add two focused tests.

## Test strategy

- `uv run pytest` (full suite).
- New assertions above.
- Manual smoke: render both templates via `render_template` and eyeball the output.

## Open questions

Resolved pre-implementation:

1. Skill name: `issueflow-issue-comments` (accepted).
2. No raw-comment appendix — keep it lean with only the curated summary.
3. No explicit edits to `/issue-yolo` or `/iflow`; they inherit the new behavior via `/issue-init`.
30 changes: 30 additions & 0 deletions .issueflows/03-solved-issues/issue45_status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Status for issue #45: include issue comments

- [x] Done

## What was done

- `/issue-init` now fetches GitHub issue comments alongside body (`gh issue view --json title,body,url,number,comments`) and triages them into a curated section written to `issue<N>_original.md`.
- Added a new skill `issueflow-issue-comments` describing how to triage the comment thread into three buckets (Additional tasks, Clarifications / constraints, Superseded / retracted) with chronological precedence, noise filtering, and edge-case handling.
- Updated `issueflow-issue-init` skill to mirror the new fetch + triage step and to delegate to the new skill.
- Registered the new skill in `TEMPLATE_MANIFEST` so `issue-flow update` emits it into `{agent_dir}/skills/issueflow-issue-comments/SKILL.md`.

## Files changed

- [src/issue_flow/templates/commands/issue-init.md.j2](../../src/issue_flow/templates/commands/issue-init.md.j2) — fetch comments, add triage step (2a), extend file format with optional `## Comments (curated summary)` section, update output + constraints.
- [src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2](../../src/issue_flow/templates/skills/issueflow_issue_init/SKILL.md.j2) — mirror the command changes; delegate to the new skill.
- [src/issue_flow/templates/skills/issueflow_issue_comments/SKILL.md.j2](../../src/issue_flow/templates/skills/issueflow_issue_comments/SKILL.md.j2) — new skill with triage rules, three buckets, output contract, and edge cases.
- [src/issue_flow/templating.py](../../src/issue_flow/templating.py) — added the new skill entry to `TEMPLATE_MANIFEST`.
- [tests/test_templating.py](../../tests/test_templating.py) — bumped manifest count to 21, added `issueflow_issue_comments` to the expected-skills list, and added three focused tests (`test_issue_init_fetches_and_triages_comments`, `test_issue_init_skill_delegates_to_comments_skill`, `test_issue_comments_skill_documents_triage_rules`).

## Tests

- `uv run pytest -q` → 71 passed.
- No linter errors on changed files.

## Remaining work

None. Both tasks in the original issue are covered:

1. `/issue-init` goes through the comments and includes tasks from them (non 1-to-1 curated summary, honors chronological precedence so later comments can supersede earlier ones).
2. A new skill (`issueflow-issue-comments`) describes how to review the comments and extract relevant tasks.
2 changes: 2 additions & 0 deletions HISTORY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ than the GitHub release notes they link to.

## [Unreleased]

- `/issue-init` now fetches GitHub issue comments and writes a curated "Comments (curated summary)" section into `issue<N>_original.md` (later comments win over earlier ones). New `issueflow-issue-comments` skill documents the triage rules (three buckets, noise filtering, edge cases). (#45)

## [0.2.3] - 2026-04-19

- **Dependency awareness at install time (#18).** A new `Prerequisites` section in the README documents the external CLI tools the scaffolded workflow shells out to (`git`, `gh` — with install hints per OS and a `gh auth login` reminder), and `issue-flow init` / `issue-flow update` now run a `shutil.which`-based dependency check up front. If anything is missing, the CLI prints the install hints and asks for confirmation before continuing. The prompt is auto-skipped on non-TTY stdin (CI) and can be bypassed explicitly with `--skip-dep-check`.
Expand Down
37 changes: 29 additions & 8 deletions src/issue_flow/templates/commands/issue-init.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,22 @@ The text after this slash command is the **issue reference**. It may also be **e
- support both SSH and HTTPS remote URL formats
- if parsing fails, ask the user for either full issue URL or `owner/repo`

2. Fetch issue data using GitHub CLI (explicit repo if needed):
- title
- body
- url
- number
- and confirm resolved `owner/repo`
2. Fetch issue data using GitHub CLI (explicit repo if needed). Include comments so they can be triaged into the original file:
- `gh issue view <N> --repo owner/repo --json title,body,url,number,comments`
- `comments` returns an array where each entry has at least `author.login`, `body`, and `createdAt`.
- Confirm resolved `owner/repo` to the user.

2a. **Triage comments** (only if the `comments` array is non-empty).
- Follow the `issueflow-issue-comments` skill (`{{ agent_dir }}/skills/issueflow-issue-comments/SKILL.md`) for the rules; summary:
- Process comments in chronological order. **Later comments win conflicts** with earlier ones.
- Sort each useful point into one of three buckets:
- **Additional tasks** — new work that isn't already in the issue body.
- **Clarifications / constraints** — guidance on *how* to do the existing work (scope, non-goals, style preferences, must-keep behaviors).
- **Superseded / retracted** — earlier tasks or preferences that later comments walked back or contradicted.
- Collapse duplicates; drop chit-chat, "LGTM" / emoji-only / bot messages.
- Paraphrase; quote sparingly. The section is an **interpretive summary**, not a verbatim dump.
- If all comments are noise (bot-only, pure chit-chat), skip the section entirely rather than writing an empty one.
- If multiple authors openly disagree and no one "wins", record the disagreement under *Clarifications* rather than guessing a winner.

2.5. **Branch status preflight** (report only; do not block and do not delete anything).
- Run `git fetch --prune` so tracking info is fresh.
Expand All @@ -55,7 +65,7 @@ The text after this slash command is the **issue reference**. It may also be **e

4. Create this file:
- `{{ issueflows_dir }}/{{ current_issues_folder }}/issue<number>_original.md`
5. File content format:
5. File content format. The `## Comments (curated summary)` section is **optional** — include it only when the triage step (2a) produced at least one bullet; omit it entirely otherwise:
```markdown
# Issue #<number>: <title>

Expand All @@ -64,7 +74,17 @@ The text after this slash command is the **issue reference**. It may also be **e
## Original issue text

<body exactly as in GitHub issue>

## Comments (curated summary)

- **Additional tasks**: <bullets distilled from comments that add real work>
- **Clarifications / constraints**: <bullets the agent should honour>
- **Superseded / retracted**: <earlier points later contradicted or walked back>

_Note: this section is an interpretive summary of the comment thread, not a verbatim dump. Source comments: <count>, last comment by @<login> on <date>._
```
- Drop any of the three bullet groups that have no content (do not keep empty `- **...**:` lines).
- Keep the `_Note: ..._` footer whenever the section is present so readers can tell where the summary came from.
6. If `gh` is not authenticated or issue fetch fails:
- stop and report the exact error
- suggest `gh auth login`
Expand All @@ -78,11 +98,12 @@ Report:
- repository used (`owner/repo`)
- if the issue number was inferred from the current branch after the user confirmed in step **1 A**, state the branch name and that `#NN` was inferred from it
- file path created
- how many comments were fetched and how many survived triage (e.g. "12 comments fetched, 4 surfaced as tasks/clarifications, 2 marked superseded"); say so explicitly when the curated section was omitted (no comments or all noise)
- archive moves performed (source -> destination, grouped by issue number)
- whether the operation succeeded

## Constraints
- Preserve the issue body exactly as returned by GitHub.
- Preserve the issue **body** exactly as returned by GitHub (the `## Original issue text` section is byte-for-byte). Only the `## Comments (curated summary)` section is interpretive.
- Use UTF-8 markdown.
- Allowed file modifications for this command:
- create/update the target `issue<number>_original.md`
Expand Down
Loading
Loading