feat(#480): /handover checklist-first doc selection + template pick#481
Merged
atlas-apex merged 1 commit intoJun 2, 2026
Merged
Conversation
- Add step 5.6 "Document selection (checklist)" after the assessment is computed: operator opts in to which artefacts to generate from a numbered catalogue (L2/L1 C4 diagrams, DFD, Feature Inventory, journey, vision, sequence). The handover assessment + harnessability score are always written and never appear in the checklist — they are the core output. - Add a per-doc template-pick sub-step for each selected template-backed doc: list candidates resolved via the existing portfolio_resolve_template (framework templates/** + adopter custom-templates/** override), default to the conventional template so --all/"default" runs stay byte-stable. - Distinguish computed/toggle-only rows (no template choice) from template-backed rows (choose-a-template) explicitly in the prompt. - Default behaviour is the interactive checklist (--interactive); --all is the non-interactive escape that generates the full default set with conventional templates, byte-for-byte the pre-checklist flow. Documented in the Usage section + argument-hint. - Add step 6.1 to generate the in-skill L1 context + sequence stubs when selected; richer docs (DFD/inventory/journey/vision) hand off to their owning skills rather than being reimplemented. - Wire CONTAINER_TEMPLATE/CONTEXT_TEMPLATE/SEQUENCE_TEMPLATE through to the generation steps; widen bootstrap-exemption scope to the new stubs; add Rules 19-20; update Output-location + step 10 summary. - Update the /handover one-liner in CLAUDE.md (counts unchanged). - Record the decision in docs/agdr/AgDR-0057-handover-checklist-selection.md (interactive-with---all-escape default + reuse of template resolution). Closes #480 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
atlas-apex
commented
Jun 2, 2026
atlas-apex
left a comment
Collaborator
Author
There was a problem hiding this comment.
Code Review: PR #481
Commit: 91e51d3055cd55bda7434edb392c3da6d2b36f0f
Verdict is APPROVED, posted as a comment because GitHub blocks self-approval (PR author == reviewer identity). The
481-rex.approvedmarker (bare HEAD SHA) is written for the merge gate.
Summary
Makes /handover present an opt-in document-selection checklist (new step 5.6) after the computed core (assessment + harnessability), lets the operator pick a template per template-backed doc via the existing portfolio_resolve_template mechanism, and adds an --all non-interactive escape that reproduces today's full set byte-for-byte. Docs/skill-only change: SKILL.md, a CLAUDE.md one-liner, and a new AgDR-0057.
Checklist Results
- Architecture & Design: Pass (checklist slots after the computed core, before doc generation)
- Code Quality: Pass (reuses
portfolio_resolve_template/portfolio_registry; no reinvented resolution; per-bash-block source preamble preserved) - Testing: N/A (skill doc — verified via site-counts + internal consistency, no executable tests exist)
- Security: Pass (no auth/secrets/crypto surface)
- Performance: N/A
- PR Description & Glossary: Pass (6-term glossary; narrative summary bullets)
- Summary Bullet Narrative: Pass (every bullet answers what + why)
- Technical Decisions (AgDR): Pass (AgDR-0057 included,
<!-- agdr: -->marker present, referenced in Rules 19-20) - Adopter Handbooks: N/A (no handbooks apply to a markdown-only docs/skill diff; semantic index empty — fail-soft to path-convention)
Issues Found
None.
Verification performed
- Step ordering: 5 → 5.5 → 5.6 → 6 → 6.1 → 7 → 7.5 → 8 → 9 → 10. The checklist (5.6) is correctly inserted after the assessment (5) / harnessability (4.5) compute and before doc generation (6).
- Cross-references resolve: every in-text reference (step 4.5, step 5, step 6, step 6.1, step 8's follow-up offer, step 10 summary, step 5.5 topology) points at a real heading.
- Helper reuse confirmed:
portfolio_resolve_templateandportfolio_registryare real functions in_lib-portfolio-paths.sh(lines 504, 142). The per-doc pick threads$CONTAINER_TEMPLATE/$CONTEXT_TEMPLATE/$SEQUENCE_TEMPLATEwith${VAR:-$(portfolio_resolve_template …)}fallbacks — no new resolution code, and--all/unset cleanly falls through to conventional resolution. - Computed-vs-template split is correct: assessment + harnessability are always-written and explicitly excluded from the catalogue; Feature Inventory / journey are toggle-only (no template pick); container/context/dfd/vision/sequence are template-backed.
- All catalogue templates exist:
templates/architecture/{c4-container,c4-context,dfd,vision,sequence}.mdall present. - Bootstrap exemption widened to cover the new
architecture/context.md+architecture/sequence-<flow>.mdwrites (sameprojects/<name>/class already exempt) — preamble + clone/reindex steps intact. - site-counts green: 57 skills / 37 hooks / 20 roles unchanged (no new skill/hook/role).
test_site_counts.shPASS.
On the default-change-to-interactive decision (you asked me to judge)
I agree with keeping interactive as the default and --all as the escape. The change is discoverable (a single prompt with a sensible default — the L2 container pre-ticked), --all preserves scripted reproducibility byte-for-byte, and /handover is a bootstrap-class interactive skill where the operator is always present, so the prompt cost is low. AgDR-0057's Options table fairly weighs the --all-default alternative and rejects it on the grounds that the valuable feature would be rarely rediscovered — that's a sound call. No change requested here.
Suggestions
- nit (non-blocking): the PR notes MD060 (table-pipe-spacing) findings from a newer markdownlint than CI's pinned
markdownlint-cli2-action@v16. Not in the gating linter so it won't block, but worth normalising the new tables' pipe spacing next time the file is touched, to avoid drift when CI's linter is eventually bumped.
Verdict
APPROVED
🤖 Reviewed by Rex (Code Reviewer Agent)
📌 Reviewed commit: 91e51d3055cd55bda7434edb392c3da6d2b36f0f
5 tasks
me2resh
added a commit
that referenced
this pull request
Jun 5, 2026
…481) - Add step 5.6 "Document selection (checklist)" after the assessment is computed: operator opts in to which artefacts to generate from a numbered catalogue (L2/L1 C4 diagrams, DFD, Feature Inventory, journey, vision, sequence). The handover assessment + harnessability score are always written and never appear in the checklist — they are the core output. - Add a per-doc template-pick sub-step for each selected template-backed doc: list candidates resolved via the existing portfolio_resolve_template (framework templates/** + adopter custom-templates/** override), default to the conventional template so --all/"default" runs stay byte-stable. - Distinguish computed/toggle-only rows (no template choice) from template-backed rows (choose-a-template) explicitly in the prompt. - Default behaviour is the interactive checklist (--interactive); --all is the non-interactive escape that generates the full default set with conventional templates, byte-for-byte the pre-checklist flow. Documented in the Usage section + argument-hint. - Add step 6.1 to generate the in-skill L1 context + sequence stubs when selected; richer docs (DFD/inventory/journey/vision) hand off to their owning skills rather than being reimplemented. - Wire CONTAINER_TEMPLATE/CONTEXT_TEMPLATE/SEQUENCE_TEMPLATE through to the generation steps; widen bootstrap-exemption scope to the new stubs; add Rules 19-20; update Output-location + step 10 summary. - Update the /handover one-liner in CLAUDE.md (counts unchanged). - Record the decision in docs/agdr/AgDR-0057-handover-checklist-selection.md (interactive-with---all-escape default + reuse of template resolution). Closes #480 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/handovercomputes the assessment + harnessability score, it now presents a numbered catalogue of the optional artefacts (L2/L1 C4 diagrams, DFD, Feature Inventory, journey, vision, sequence) and lets the operator pick which to generate viadefault/all/none/ a comma-list /+N -Ntoggles. Previously the doc set was fixed, so a pure-backend handover still got a container diagram and a UI-heavy one couldn't request a journey or DFD. The handover assessment + harnessability score are always written and never appear in the checklist — they are the skill's core output.portfolio_resolve_templatemechanism (frameworktemplates/**+ adoptercustom-templates/**override) and anOtheroption for sibling variants. The default is always the conventional template — the path the helper would pick unprompted — so--alland "default" runs stay byte-stable. This exposes adopter overrides that were previously unreachable from the skill, without any new resolution code.--allescape — the checklist is the default (--interactivenames it for scripts);--allgenerates the full default set with conventional templates and no prompt, byte-for-byte the pre-checklist flow. This realises the issue's recommended shape while keeping scripted runs reproducible by adding one flag. Documented in Usage +argument-hint./dfd,/extract-features,/journey,/tech-vision) rather than being reimplemented, mirroring step 8's follow-up offer.CONTAINER_TEMPLATE/CONTEXT_TEMPLATE/SEQUENCE_TEMPLATEthread the per-doc pick into the generation steps; bootstrap-exemption scope widened to the new stubs; Rules 19–20 added; Output-location + step 10 summary updated;/handoverone-liner inCLAUDE.mdrefreshed (skill/hook/role counts unchanged).Testing
bash .claude/hooks/tests/test_site_counts.sh→ PASS (57 skills / 37 hooks / 20 roles — unchanged; no new skill/hook/role added).npx --no-install markdownlint-cli2 --config .markdownlint.json .claude/skills/handover/SKILL.md docs/agdr/AgDR-0057-*.md CLAUDE.md→ only MD060 (table-pipe-spacing) findings, which are not in CI's pinnedmarkdownlint-cli2-action@v16linter; no MD022/MD032/MD040-class errors.--allskip-path, the template-pick fallback (${CONTAINER_TEMPLATE:-$(portfolio_resolve_template …)}), and the selection-condition guards in steps 6 / 6.1 all reference variables set in step 5.6. No executable tests exist for a skill doc — verification is lint + site-counts + internal consistency.Glossary
templates/**or an adoptercustom-templates/**override), as opposed to a computed/toggle-only output assembled from the repo scanportfolio_resolve_template_lib-portfolio-paths.shthat resolves a template path with adopter-override semantics (custom override first, framework default second)--all/dfd,/extract-features,/journey,/tech-vision) instead of reimplementing its output inlinerequire-active-ticket.shcarve-out that lets/handoverwriteprojects/<name>/files before a tracker ticket existsCloses #480