feat(comments): `renderIssueComment` owns comment layout — headline and AC table visible, everything else in one `<details>` block; adopted by the QA verdict, merge-check and review-residue builders; hidden `sequant comment render` for skills
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 42/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- node.js, typescript
- Domain
- developer-experience, tooling
Research direction
Read the existing buildQaVerdictComment implementation in src/lib/workflow/batch-executor.ts and the builders in src/lib/merge-check/report.ts and src/lib/workflow/review-residue.post.ts. Then inspect the parser coverage in src/lib/workflow/batch-executor.test.ts and the specified merge-check tests. Done means all three builders use the shared renderer, the new CLI command handles fixture input, and the listed Vitest checks pass without changing skill directories.
Written by the indexing model from the issue text.
Description
Epic: graph-2026-10-ergonomics Tier: mechanical Execution: sequant_run Blocked by: #1602, #1521 (both edit buildQaVerdictComment; #1525 parses its output)
- Blocked by: #1602
- Blocked by: #1521
Problem
Across 15 recently completed issues the generated comments total 130k characters (spec comments 4.5k–14k each, QA reviews up to 9.6k). Every later phase and the owner re-read them. No skill or TS builder uses <details>. Layout is decided by whichever skill or function writes the comment, which is the prose-geometry defect #823 removed from the assess dashboard. §5 D-3.1 of the founding doc.
Decisions
| ID | Decision | Rejected alternative |
|---|---|---|
| L-1 | One function, renderIssueComment({kind, headline, acTable?, sections}), renders headline, optional AC table, then every section inside a single <details><summary>Details</summary> block. Every line a parser anchors on (QA_VERDICT, the per-AC status rows #1525 reads, SEQUANT_MUTATION, assess markers) stays outside the block and keeps its current position |
per-builder <details> sprinkled by hand |
| L-2 | buildQaVerdictComment, merge-check/report.ts and review-residue.post.ts call it |
leaving the TS builders as they are and only changing skills |
| L-3 | Hidden sequant comment render --kind spec|qa --body-file - reads a body whose first line is the headline and whose first markdown table is the AC table, and prints the laid-out comment; interactive skills pipe through it (#1606) |
a prose instruction "wrap in details" in each skill |
Acceptance Criteria
- AC-1: The renderer puts the headline and AC table outside and every other section inside one
<details>block, with markers outside. Evidence:npx vitest run src/lib/workflow/comment-layout.test.ts→≥ 5 passed, 0 failed - AC-2: The QA verdict comment still parses the same verdict and per-AC statuses after adoption. Evidence:
npx vitest run src/lib/workflow/batch-executor.test.ts -t "verdict comment"→0 failed - AC-3: Merge-check and review-residue comments adopt the layout and their existing tests pass. Evidence:
npx vitest run src/lib/merge-check src/lib/workflow/review-residue.post.test.ts→0 failed - AC-4:
sequant comment render --kind qaon a fixture body produces output whose visible part is the headline plus the AC table. Evidence:npx vitest run src/commands/comment-render.test.ts→≥ 2 passed, 0 failed - AC-5: No skill-directory edits. Evidence:
git diff --name-only $(git merge-base origin/main HEAD)..HEAD | grep -cE '^(plugin/|\.claude/skills/|templates/skills/)'→0(constraint)
May touch
src/lib/workflow/comment-layout.ts (new) and test, src/lib/workflow/batch-executor.ts (buildQaVerdictComment only), src/lib/merge-check/report.ts, src/lib/workflow/review-residue.post.ts, src/commands/comment-render.ts (new), bin/cli.ts, CHANGELOG.
Non-Goals
- Shortening or summarising content; layout only.
- Changing any skill (frozen; #1606).
Done when
A reader opening an issue sees the verdict or recommendation and the AC table, and nothing else until they expand it, for every comment sequant's code writes.
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 1
- Avg merge
- 11h 3m
- Merged PRs (30d)
- 84
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from sequant-io/sequant
-
graph-2026-11-simplify
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
sequant-io/sequant#1650 ·
Maintainers usually reply within 1 day
-
run: --phases does not suppress the UI-label test phase (determinePhasesForIssue adds it to an explicit list)Possibly taken @admarble claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
sequant-io/sequant#1631 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
sequant-io/sequant#1601 ·
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
sequant-io/sequant#1582 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 76/100
sequant-io/sequant#1381 ·
Maintainers usually reply within 1 day
All issues in sequant-io/sequant
Similar issues
-
content triage
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
tensorflow/tfjs#8754 ·
-
tool-submission
Difficulty 1/5 Under an hour Newbie friendliness 83/100
BraveOPotato/NoSignups#2348 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
code-yeongyu/oh-my-openagent#12784 ·
Maintainers usually reply within 1 day
-
external-issue to-triage
Difficulty 2/5 1-3 hours Newbie friendliness 71/100
Maintainers usually reply within 1 day