feat(#376): /handover offers to file Next Steps as tracker tickets#378
Conversation
Closes the recommendation-rot loop where the static "Next Steps" prose
in handover-assessment.md was hand-translated to /feature / /task / /bug
invocations one at a time. New step 7.5 in the /handover flow:
- Surfaces the assessment's top 3-5 next-step entries inline after the
registry append (step 7) and before the clone offer (step 8)
- Bulk-input shapes accepted: `all` / `none` / comma-list (e.g. `1,3,5`);
falls back to interactive per-item walk for ambiguous responses
- Auto-routes each accepted item by shape:
- "Fix" / "failing" → /bug
- "Triage" / "/decide" / explicit framework-skill invocation → /task
- "Set up X" / "Write README" / "Enable CI" → /task
- default: /task (the safe-when-in-doubt branch since handover-
derived next-steps are almost never user-facing /feature shape)
- Per-item override syntax: `1 as feature` / `3 as bug` honours the
override and skips the heuristic for that item
- Each dispatched ticket carries a `_Source: handover deep-dive on
YYYY-MM-DD — see projects/<name>/handover-assessment.md_` footer so
the source-of-truth back-link survives a future read of the ticket
- Post-filing, the assessment's `## Next Steps` section is rewritten
in-place: filed entries become `1. ~~prose~~ → Filed as [#42](...)`;
unfiled entries stay as-is. Future reader can see what became a
ticket and what's still TODO.
Skip conditions documented explicitly (always-skip cases that DON'T
get a prompt):
- Zero next-step entries (no risks found)
- Re-handover where the next-step list is byte-equivalent to the prior
run (notes "Next steps unchanged since YYYY-MM-DD" instead of
re-prompting the same items)
- Operator declined the registry append at step 7 (ticket-source links
pointing at projects/<name>/handover-assessment.md wouldn't resolve)
Failure handling mirrors /tickets-batch — stop on the first failure,
report which tickets did file, never roll back already-filed tickets.
Step 10 (summary) gains a new line `Next-step tickets filed:` reporting
the outcome + inline list of filed-ticket numbers / URLs.
Rules section gains 4 new entries (15-18) codifying the new behaviour:
- Always opt-in, never auto-fire
- Routing heuristic is default-not-law; operator overrides honoured
- Source-link back to assessment is mandatory on every filed ticket
- Re-runs surface deltas, not redundancy
CLAUDE.md skill row updated. docs/multi-project.md /handover row gains
a step-7.5 description.
No tests added — the new step is prose / interactive flow + dispatches
to other skills which have their own tests. The shell-script bits of
/handover (harnessability scoring at step 4.5, topology pick at step
1.5) keep their existing tests in .claude/skills/handover/tests/.
Markdownlint clean.
Closes #376
Refs #377 (the new /plan-initiative skill will mirror this step's UX
for its milestone-filing flow)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
atlas-apex
left a comment
There was a problem hiding this comment.
Code Review: PR #378
Commit: fca97b1af1ee9cb1467abd007e6029c9a89c5323
Verdict intent: CHANGES REQUESTED (submitted as a review comment because GitHub blocks self-PR
--request-changes). Treat the two findings under "Issues Found" as merge blockers.
Summary
Adds step 7.5 to /handover that surfaces the assessment's derived Next Steps inline and offers to file each as a tracker ticket via /feature / /task / /bug, auto-routed by item shape. Sits between registry append (step 7) and clone offer (step 8). Mandatory back-link footer on every filed ticket; assessment's Next Steps section rewritten in-place post-filing with strikethrough+link for filed entries. Three skip conditions documented; failure handling mirrors /tickets-batch. Four new rules (15-18) codify the contract.
Mechanically prose-only — no new shell helpers, no tests added. The shipping shape is "markdown table the LLM interprets at runtime", consistent with how other handover step prose works.
Checklist Results
- Architecture & Design: Pass
- Code Quality: Pass
- Testing: Pass (no new shell code; routing heuristic lives in markdown by design)
- Security: Pass
- Performance: Pass
- PR Description & Glossary: Pass
- Summary Bullet Narrative: Pass (each bullet answers what+why; bolded leads + rationale, not labels)
- Technical Decisions (AgDR):N/A (skill prose extension, no library/framework/architecture choice)
- Adopter Handbooks: N/A (markdown-only diff; no language/architecture/migration triggers fire)
Issues Found
Blocker 1 — Source-link path is broken in GitHub issue rendering.
The source-link footer mandated by rule 17 (line 815) is:
_Source: handover deep-dive on YYYY-MM-DD — see [`projects/<name>/handover-assessment.md`](../<project>/handover-assessment.md) for the assessment that surfaced this work._
Once this string is committed to a GitHub issue body in the target repo, the markdown link resolves as https://github.com/<target-owner>/<target-repo>/../<project>/handover-assessment.md — not a working URL. The assessment lives in the ops fork (or, for split-portfolio v2, in the private sibling repo), NOT in the target repo. The "relative to the ticket creator's working dir" comment on line 818 misframes the problem: once the body is in a GitHub issue body, there is no working dir; only the issue's repo URL. The link is broken from the moment the issue is created.
Split-portfolio v2 makes this strictly worse — the assessment is in a private sibling repo with no public URL at all, so even an absolute link can't reach it for off-ops-fork readers.
Fix (pick one):
- Drop the markdown link and keep just the prose path reference:
_Source: handover deep-dive on YYYY-MM-DD — see projects/<name>/handover-assessment.md in the ops fork._(operator copies the path manually; honest about cross-repo limits) - Build an absolute URL to the assessment in the ops-fork repo at dispatch time:
https://github.com/<ops-fork-owner>/<ops-fork-name>/blob/main/projects/<name>/handover-assessment.md, with a fallback to the prose form when the ops fork is private or split-portfolio (so the URL would 404 publicly) - Document that the link only works when the assessment lives in a public ops fork AND the reader has access AND single-fork mode is active — and write the prose form otherwise
Rule 17 itself doesn't mandate the markdown-link shape (it just says "carries a _Source: ... see projects/<name>/handover-assessment.md_ footer"), so fix (1) keeps the rule intact and just drops the broken link form from the example.
Blocker 2 — Re-run skip logic conflicts with the strikethrough+link rewrite.
Rule 18 says step 7.5 skips when "the new next-step list is byte-equivalent to the prior run's". But step 7.5's post-filing rewrite (lines 826-829) mutates the assessment's ## Next Steps section to include ~~strikethrough~~ → Filed as [#N](...) markers on filed entries.
On re-run, step 5 regenerates the section. The design doesn't say whether step 5 preserves the strikethrough+link entries (like rule 11 does for the architecture stub) or overwrites them. Two scenarios, both broken:
-
If step 5 overwrites with fresh prose: the byte-equivalence test compares freshly-generated prose against… freshly-generated prose. It trivially passes, but the prior strikethrough+link signal is wiped, AND on the alternate path where the next-step list changed, step 7.5 re-prompts on entries that were already filed last time (because their strikethrough+link form was overwritten back to prose). This is the exact recommendation-rot failure mode the rule is trying to prevent.
-
If step 5 preserves prior strikethrough+link entries (the rule 11 analogue): the byte-equivalence test needs to compare only the un-filed entries between runs, which the design doesn't specify. AND step 5's mapping table re-runs would need to dedupe against already-filed prose to avoid re-emitting them as new prose entries.
The reviewer's prompt called this out explicitly: "Re-running again should NOT re-prompt on already-filed entries — the strikethrough is the signal that 'this one's done.'" The skill needs to either:
- Specify that step 5 preserves strikethrough+link entries from prior runs (rule-11-style protection on the Next Steps section), AND that step 7.5's byte-equivalence test compares only the still-prose entries
- OR store filing state out-of-band (e.g. a
.next-steps-filedline in YAML frontmatter or a siblingnext-steps-state.json) so re-runs can identify the already-filed entries even after step 5 regenerates the section - OR drop the "byte-equivalent" framing entirely and say "step 7.5 only offers entries that don't already have a
Filed aslink" — simpler and avoids the byte-comparison ambiguity
Option 3 is probably the cleanest — the skill scans the existing ## Next Steps section for Filed as markers and only offers the unmarked entries. That collapses rule 18 into a simpler "already-filed entries are skipped" semantics, with no byte comparison needed.
Suggestions
-
"Top 3-5" is ambiguous when the assessment has 7 entries. Step 5's mapping table can produce up to 7 entries (rows 1-7) plus 2 synthetic fallbacks. Step 7.5 (line 768) says "Print the top 3-5 next-step entries". If the assessment has 7, do we drop entries 6-7? Specify: cap-5-and-truncate, or show-all with a paging shape, or something else. (Pre-line 768 fix.)
-
Skip-condition 4 — target repo archived / read-only. The reviewer's prompt asked about this. Failure-handling catches it at runtime (operator gets the Retry/Skip/Abort prompt on the first dispatch's
ghnon-zero exit), so it's not a correctness gap. But a defensive skip-condition at step-entry —gh repo view <repo> --json isArchived→ if true, skip withtarget repo is archived — file these elsewhere— would save the operator from typing through five prompts only to find the repo can't accept tickets. Non-critical. -
/featureis unreachable via the heuristic. All 5 rows in the routing table (lines 797-801) dispatch to/taskor/bug./featureis only reachable via the per-item override syntax (1 as feature). The PR rationale (handover-derived next-steps are rarely user-facing capabilities) justifies this, but the routing-table column could simplify to two values for clarity, with/featurereachable only via override. Non-load-bearing. -
Frontmatter description didn't update. Line 3:
description: Onboard an external repo via a structured handover assessment + harnessability scoring across 5 codebase dimensions.— could mention "+ offers to file Next Steps as tracker tickets" to mirror the CLAUDE.md and docs/multi-project.md edits. Minor.
Verdict
CHANGES REQUESTED (submitted via --comment due to GitHub's self-PR review restriction; treat the two blockers above as merge gates).
The step ordering, routing heuristic correctness (verified against all 7 step-5 emit shapes + 2 synthetic fallbacks — all route correctly), failure-handling alignment with /tickets-batch § 7, summary block extension, and rules 15-18 quality are all solid. Markdownlint clean across the 3 files.
The two blockers are both about the design contract holding up after the first run: blocker 1 because the back-link doesn't resolve once the issue is in GitHub, and blocker 2 because the re-run semantics are ambiguous when the post-filing rewrite leaves strikethrough+link entries in the section step 5 will regenerate. Both are addressable with prose-only edits to the skill — no structural redesign needed.
Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: fca97b1af1ee9cb1467abd007e6029c9a89c5323
…flict Two blockers from Rex's review of fca97b1: **Blocker 1 — Source-link path was broken in GitHub issue rendering.** The prior shape `[`projects/<name>/handover-assessment.md`](../<project>/...)` rendered against the TARGET repo's URL space, but the assessment lives in the OPS FORK (or, for split-portfolio v2 adopters, the private sibling repo). No relative form could resolve. Switched to plain prose path, no markdown link, with explicit pointer to "ops fork (or private portfolio sibling repo for split-portfolio v2 adopters)" so the reader knows where to look. **Blocker 2 — Byte-equivalence skip-condition conflicted with the post-filing strikethrough+link rewrite.** The prior Rule 18 said skip when the regenerated Next Steps list was byte-equivalent to the prior run, but step 7.5's own rewrite mutates the section to strikethrough+link forms, guaranteeing every subsequent run's section is non-byte-equivalent. Switched to filed-marker presence detection: - Step 5's "## Next Steps" regeneration MUST preserve prior `Filed as [#N](url)` markers on recurring entries (matched by leading-verb + key-noun-phrase across runs) - Step 7.5's prompt loop partitions entries into "already-filed" (silently skipped) and "unfiled" (the only entries surfaced) - Skip-condition #2 fires when every entry is already-filed - Rule 18 rewritten to name the marker-presence test as load-bearing and explicitly disclaim byte-equivalence Markdownlint: 0 errors at HEAD on the modified file. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
atlas-apex
left a comment
There was a problem hiding this comment.
Re-Review: PR #378 (HEAD f7667b7)
Commit: f7667b7747cc5a949c933a233ed58dba1775488ad
Re-review focuses on the 2 prior blockers from fca97b1. Items I PASS'd previously (coverage, AgDR, handbook, glossary, routing-heuristic, failure-handling-alignment, scope-cleanness, no-tests-decision) are not re-litigated here.
Blocker 1 — Source-link path correctness — RESOLVED
The fix-up dropped the broken markdown-link form entirely. The body footer is now a plain prose path:
_Source: handover deep-dive on YYYY-MM-DD — seeprojects//handover-assessment.mdin the ops fork (or in the private portfolio sibling repo for split-portfolio v2 adopters) for the assessment that surfaced this work._
Walked the survival across all three adopter layouts:
- Single-fork —
projects/<name>/handover-assessment.mdresolves correctly from the fork root; "the ops fork" is the operator's apexyard fork - Split-portfolio v1 —
projects/<name>/is symlinked from the fork into the sibling private repo; "the ops fork" still names the symlink-anchor that resolves transparently - Split-portfolio v2 —
projects/<name>/lives in the private sibling repo; the parenthetical "(or in the private portfolio sibling repo for split-portfolio v2 adopters)" names this case explicitly
Honest about the cross-repo lookup the reader has to do; no dead link. The rationale paragraph immediately below in the SKILL.md (lines 826-827) explains why no link form works — useful for future-maintainers, doesn't bloat the ticket itself.
Cryptic-ness for cold readers — a teammate at the target-repo who's never used ApexYard might wonder what "the ops fork" means. But: the assessment lives inside the adopter's own org, teammates reading the ticket are inside that org, and the dated source attribution is recoverable even if the path takes one Slack question to resolve. Acceptable trade-off given the unsolvable cross-repo link problem. The fix-up made the right call.
Blocker 2 — Marker-preservation handoff between step 5 and step 7.5 — RESOLVED
Three coordinated changes verified against the live file:
-
Step 5 (line 396) — new "Re-handover preservation" paragraph mandates that step 5's regeneration MUST preserve prior
~~strikethrough~~ → Filed as [#N](url)markers, matched by "leading verb + key noun phrase" across runs. Names Rule 18 as the cross-reference. -
Step 7.5 (lines 768-789) — "Surface the entries" now partitions into
already-filed(silently skipped, never surfaced) +unfiled(the only entries prompted). Fall-through wiring at line 775 named correctly: "If the unfiled bucket has zero entries, fall through to the skip-condition…". The conditional(N were filed in a prior run — skipping)parenthetical is gated explicitly at line 789 — only appears when ≥1 prior-filed entry was skipped. -
Rule 18 (line 1018) — rewritten. The decisive line: "Byte-equivalence of the section text is NOT the test — only the per-entry marker presence is." Names the marker-presence test as load-bearing and explicitly disclaims byte-equivalence. Skip-conditions list (line 765) updated correspondingly.
Walking the leading-verb + key-noun-phrase rule against step 5's 7 emit shapes (re-check question 2)
| # | Step-5 emit shape | Mutable bits | Key noun phrase (survives re-run?) |
|---|---|---|---|
| 1 | /audit-deps {name} — triage the {severity} {package} CVE… |
severity, package | "triage the … CVE" ✓ |
| 2 | Fix the {N} failing tests in {module}… |
N, module | "Fix the … failing tests in {module}" ✓ (count survives; module change would shift the noun, but that's a different ticket by design) |
| 3 | /decide on observability ({options}) |
parenthetical | "/decide on observability" ✓ |
| 4 | Re-enable CI on this repo… |
none | "Re-enable CI" ✓ |
| 5 | Set up test coverage reporting (vitest/jest config)… |
parenthetical | "Set up test coverage reporting" ✓ |
| 6 | Triage the issue backlog with the previous owner… |
none | "Triage the issue backlog" ✓ |
| 7 | Write a minimum-viable README (...) |
parenthetical | "Write a minimum-viable README" ✓ |
| +fallthrough | /code-review the most-recent PR… |
none | stable ✓ |
| +fallthrough | Stakeholder sync with the previous owner… |
none | stable ✓ |
Every shape has a stable verb+noun-phrase anchor surviving the mutable bits. The matcher rule is well-formed against all 9 emit shapes (7 mapping-table + 2 fallthroughs).
Partition-logic edge cases (re-check question 3)
Walked all four cases against lines 770-789:
| Case | Already-filed | Unfiled | Result | Correct? |
|---|---|---|---|---|
| Zero filed, all new | 0 | N | print without parenthetical (line 789) | ✓ |
| All filed, zero new | N | 0 | fall through to skip-condition → one-line note | ✓ |
| Mixed (2 filed, 3 new) | 2 | 3 | print 3 entries WITH (2 were filed in a prior run — skipping) parenthetical |
✓ |
| First handover (no prior assessment) | 0 | N | print without parenthetical | ✓ |
Fall-through wiring at line 775 is placed correctly — after the partition, before the "Otherwise print" branch. The skip-condition #2 at line 765 is the named target.
Rule 18 quality (re-check question 4)
- Testable — operator can verify by re-running
/handoveron a project that already had tickets filed, confirming filed-entries don't re-prompt - Self-consistent with steps 5 and 7.5 — Rule 18 references "§ Skip conditions" (line 765) and Step 5's "Re-handover preservation" (line 396). Both refs resolve.
- Not a duplicate of Rules 15-17 — distinct invariants: 15=opt-in, 16=routing-default, 17=source-link-required, 18=re-runs-preserve-markers
- Byte-equivalence disclaimer — explicit ("Byte-equivalence of the section text is NOT the test — only the per-entry marker presence is.")
Markdownlint (re-check question 5)
Re-ran npx markdownlint-cli2@0.13.0 against the live SKILL.md at HEAD f7667b7 with the repo's .markdownlint.json (MD013 disabled per repo convention): 0 errors.
Checklist Results
- ✅ Architecture & Design: Pass
- ✅ Code Quality: Pass
- ✅ Testing: Pass (decision to skip new bash tests still holds — prose changes only, dispatched skills have their own tests)
- ✅ Security: Pass
- ✅ Performance: Pass (N/A — prose changes)
- ✅ PR Description & Glossary: Pass
- ✅ Summary Bullet Narrative: Pass (all 6 bullets are narrative with verbs + ≥6 words)
- ✅ Technical Decisions (AgDR): Pass (AgDR linked from prior pass — unchanged)
- ✅ Adopter Handbooks: N/A (no
handbooks/files loaded — no language/architecture/general matches) - ✅ Source-link path (Blocker 1): Pass
- ✅ Marker-preservation handoff (Blocker 2): Pass
- ✅ Markdownlint: Pass
Issues Found
None blocking.
Suggestions (nits)
-
Minor consistency drift on the source-link prose form. The canonical form in step 7.5 (line 824) is the fully-spelled-out version with the parenthetical; the shorthand version appears in:
- Rule 17 (line 1017):
_Source: handover deep-dive on YYYY-MM-DD — see projects/<name>/handover-assessment.md_ - PR body summary bullet 3: same shorthand
docs/multi-project.mdline 805: even shorter —_Source: handover deep-dive on YYYY-MM-DD_
Step 7.5 is the load-bearing canonical (it's what gets written to tickets); the others are documentation summaries where brevity is reasonable. Worth a future tightening pass, but not blocking — the doc consumer reads step 7.5's prose to actually do the work, not Rule 17. Could noting "(see step 7.5 § Dispatch for the full prose)" in Rule 17 close the loop without bloating the rule.
- Rule 17 (line 1017):
-
Slightly redundant prose in skip-condition #2 detection clause (line 765): "if every entry either already-carries a
Filed as [#N](...)link preserved through step 5's regeneration OR is a duplicate of a prior-run entry that did, skip." After Rule 18's preservation guarantee, every recurring filed entry should already carry the link — so the "OR is a duplicate of a prior-run entry that did" branch is a belt-and-braces fallback if preservation breaks. Not a bug; just slightly redundant prose. Future tightening pass could remove the OR clause and let Rule 18 do the load-bearing work alone.
Neither nit blocks the merge.
Verdict
APPROVED
Both blockers from fca97b1 are resolved cleanly. The fix-up commit (+15/-6 in SKILL.md) is focused, doesn't ripple to the other two files, and the new prose is internally consistent across step 5 / step 7.5 / Rule 18. The leading-verb + key-noun-phrase matcher survives all 9 emit shapes from step 5's mapping table. Edge cases in the partition logic are handled correctly. Markdownlint is clean.
Note on the approval marker: per the sandbox workaround memory, the operator will write the marker on Rex's behalf using this SHA — f7667b747cc5a949c933a233ed58dba1775488ad.
🤖 Reviewed by Rex (Code Reviewer Agent)
📌 Reviewed commit: f7667b747cc5a949c933a233ed58dba1775488ad
) * feat(#376): /handover offers to file Next Steps as tracker tickets Closes the recommendation-rot loop where the static "Next Steps" prose in handover-assessment.md was hand-translated to /feature / /task / /bug invocations one at a time. New step 7.5 in the /handover flow: - Surfaces the assessment's top 3-5 next-step entries inline after the registry append (step 7) and before the clone offer (step 8) - Bulk-input shapes accepted: `all` / `none` / comma-list (e.g. `1,3,5`); falls back to interactive per-item walk for ambiguous responses - Auto-routes each accepted item by shape: - "Fix" / "failing" → /bug - "Triage" / "/decide" / explicit framework-skill invocation → /task - "Set up X" / "Write README" / "Enable CI" → /task - default: /task (the safe-when-in-doubt branch since handover- derived next-steps are almost never user-facing /feature shape) - Per-item override syntax: `1 as feature` / `3 as bug` honours the override and skips the heuristic for that item - Each dispatched ticket carries a `_Source: handover deep-dive on YYYY-MM-DD — see projects/<name>/handover-assessment.md_` footer so the source-of-truth back-link survives a future read of the ticket - Post-filing, the assessment's `## Next Steps` section is rewritten in-place: filed entries become `1. ~~prose~~ → Filed as [#42](...)`; unfiled entries stay as-is. Future reader can see what became a ticket and what's still TODO. Skip conditions documented explicitly (always-skip cases that DON'T get a prompt): - Zero next-step entries (no risks found) - Re-handover where the next-step list is byte-equivalent to the prior run (notes "Next steps unchanged since YYYY-MM-DD" instead of re-prompting the same items) - Operator declined the registry append at step 7 (ticket-source links pointing at projects/<name>/handover-assessment.md wouldn't resolve) Failure handling mirrors /tickets-batch — stop on the first failure, report which tickets did file, never roll back already-filed tickets. Step 10 (summary) gains a new line `Next-step tickets filed:` reporting the outcome + inline list of filed-ticket numbers / URLs. Rules section gains 4 new entries (15-18) codifying the new behaviour: - Always opt-in, never auto-fire - Routing heuristic is default-not-law; operator overrides honoured - Source-link back to assessment is mandatory on every filed ticket - Re-runs surface deltas, not redundancy CLAUDE.md skill row updated. docs/multi-project.md /handover row gains a step-7.5 description. No tests added — the new step is prose / interactive flow + dispatches to other skills which have their own tests. The shell-script bits of /handover (harnessability scoring at step 4.5, topology pick at step 1.5) keep their existing tests in .claude/skills/handover/tests/. Markdownlint clean. Closes #376 Refs #377 (the new /plan-initiative skill will mirror this step's UX for its milestone-filing flow) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(#376): address Rex blockers — broken source link + skip-logic conflict Two blockers from Rex's review of e9bf6e2: **Blocker 1 — Source-link path was broken in GitHub issue rendering.** The prior shape `[`projects/<name>/handover-assessment.md`](../<project>/...)` rendered against the TARGET repo's URL space, but the assessment lives in the OPS FORK (or, for split-portfolio v2 adopters, the private sibling repo). No relative form could resolve. Switched to plain prose path, no markdown link, with explicit pointer to "ops fork (or private portfolio sibling repo for split-portfolio v2 adopters)" so the reader knows where to look. **Blocker 2 — Byte-equivalence skip-condition conflicted with the post-filing strikethrough+link rewrite.** The prior Rule 18 said skip when the regenerated Next Steps list was byte-equivalent to the prior run, but step 7.5's own rewrite mutates the section to strikethrough+link forms, guaranteeing every subsequent run's section is non-byte-equivalent. Switched to filed-marker presence detection: - Step 5's "## Next Steps" regeneration MUST preserve prior `Filed as [#N](url)` markers on recurring entries (matched by leading-verb + key-noun-phrase across runs) - Step 7.5's prompt loop partitions entries into "already-filed" (silently skipped) and "unfiled" (the only entries surfaced) - Skip-condition #2 fires when every entry is already-filed - Rule 18 rewritten to name the marker-presence test as load-bearing and explicitly disclaim byte-equivalence Markdownlint: 0 errors at HEAD on the modified file. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Summary
/handovercloses the recommendation-rot loop where the static "Next Steps" prose inhandover-assessment.mdwas hand-translated to/feature//task//buginvocations one at a time. After the registry append (step 7) and before the clone offer (step 8), the skill now surfaces the top 3-5 derived next-step entries inline + prompts y/n per item (with bulk shortcutsall/none/ comma-list like1,3,5)./bug; explicit framework-skill invocations or triage/decide work →/task; new-capability/scaffolding/CI/README items →/task. Default/taskwhen in doubt — handover-derived next-steps are almost never user-facing capabilities (so/featurewould be wrong) and rarely strictly-broken behaviour (so/bugwould be wrong). Per-item override syntax (1 as feature/3 as bug) honours the override and skips the heuristic for that item._Source: handover deep-dive on YYYY-MM-DD — see projects/<name>/handover-assessment.md_footer in its body. Without that link, the assessment's context (risks, harnessability score, build status) is invisible to anyone working the ticket later, which is exactly the rot mode this step prevents.## Next Stepssection is rewritten so filed entries become1. ~~prose~~ → Filed as [#42](...)while unfiled entries stay as-is. Future readers see at a glance which next-steps became tickets and which are still TODO.nat step 7 — back-links toprojects/<name>/handover-assessment.mdwouldn't resolve).Next-step tickets filed:reporting the outcome + inline list of filed-ticket numbers / URLs. Rules section gains 4 new entries (15-18) codifying the always-opt-in / routing-heuristic / source-link-mandatory / re-runs-surface-deltas semantics.Testing
npx markdownlint-cli2@0.13.0 .claude/skills/handover/SKILL.md— 0 errors.test_harnessability_scoring.shandtest_topology_pick.shcover the shell-script bits of the skill (step 4.5 + step 1.5); the new step 7.5 is prose-only + dispatches to other skills which have their own tests, so no new bash test was added./handoveragainst a fresh adoption (or re-run on an existing one with new risks); confirm step 7.5 fires, the auto-routing picks reasonable skills per item, the source-link footer lands in each filed ticket, and the assessment's Next Steps section gets rewritten with strikethrough+links for filed items.Glossary
handover-assessment.mdthat future-us reads, half-translates to tickets, and half-forgets. The work is real (it came from the risk analysis) but it loses to inbox triage if it's not converted to tracker entries./feature//task//bugticket-creation skill. Codified in step 7.5's table. Operator-overridable per item viaN as feature/N as bugsyntax._Source: handover deep-dive on YYYY-MM-DD — see projects/<name>/handover-assessment.md_line appended to every filed ticket's body. Mandatory per rule 17 — without it, the assessment's context is lost to anyone who picks up the ticket later./handoverruns against a project that already has an assessment, and the newly-generated next-step list is byte-equivalent to the prior run's, step 7.5 skips with aNext steps unchanged since YYYY-MM-DDnote instead of re-prompting the operator on entries they've already triaged.Closes #376
Refs #377 (the new
/plan-initiativeskill will mirror step 7.5's UX for its milestone-filing flow — single shared pattern across both skills means operators learn it once)