Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources

Brief

Restatement: confirmed by the user, round 4 ("Confirmed.").

TLDR

A program of seven workstreams that improves the planning chain from three outside sources: Thariq's html-plan, HumanLayer's rpi/show-me, Matt Pocock's skills.
Order: W1 records, W3 chain wiring, W5 accuracy checks (+ html-plan trial), W7 interview wording, W4 Brief-as-spec, W6 review speed and visuals, W2 source-intake skill.
PLAN.md stays the record; HTML is only a view. Ideas are borrowed; no dependency on outside code.
A /work-items:decompose spec container issue is the program anchor; each workstream ships from its own worktree, branch and PR.

Goal

Our planning chain (interview, PRD, design, plan, decompose) produces plans a reviewer can check in a minute, that cite only code that exists,
that link to each other correctly including a one-ticket route, and that improve continuously from recorded outside sources, while
staying inside the plugin philosophy (one owner per value, good defaults, configuration where an operator needs it).

Constraints

C1: improve our own skills, planning first, from the outside sources' ideas.
C2: Markdown is the record; HTML is a view of a record (docs/conventions/rendered-views/README.md:19-33).
C3: every workstream runs in its own worktree and feature branch, never the main checkout.
Borrow ideas only; no install, vendor or adapter dependency on html-plan or HumanLayer code (Q2).
Implementation mechanisms are settled at /planning:plan per workstream (Q5).
Plugin philosophy: configuration ownership table (docs/plugin-philosophy.md:381-393); zero-config defaults.

Acceptance criteria

A spec container issue carries this charter verbatim with W1-W7 as needs-human sub-issues, real blocked-by edges only, priority in the agreed order.
W1: docs/upstream/html-plan.md exists; docs/upstream/humanlayer-skills.md covers rpi/structure-outline; the Pocock map is re-audited against current upstream HEAD.
W3: every chain skill has a ## Next that agrees with /session-flow:workflow's ladder; nothing is an orphan; an approved one-unit Brief or plan routes to a single tracker item; a script checks the Next graph.
W5: a script fails a plan whose file:line citation does not exist; plans stamp the commit they were checked at; acceptance criteria trace to phases and slices; decompose checks each criterion can fail at the base commit.
W5: the html-plan trial ran on W5's planning and its outcome (decisions changed or not) is recorded; the temporary install is removed.
W7: interview questions are worded so a plain "yes" accepts the recommendation; an unopened default is never recorded as agreement.
W4: one artifact is declared the spec; the Goal, test-boundary and duplicate PLAN.md sections each have one owner.
W6: PLAN.md opens with a behaviour-first summary; plans use the visualize code-shape views with @ path:line; the plan view is generated from PLAN.md.
W2: a knowledge-plugin skill writes a docs/upstream record carrying each idea's problem, motivation and our disposition; default location docs/upstream/, configurable.
Each workstream PR body carries Refs: #<container>; each sub-issue closes when its PR merges.

Captured assumptions

The coverage prompt (unwanted-behavior and state-driven cases) was asked at the confirmation round; the user confirmed without adding any: revisit if a workstream is abandoned or two workstreams touch the plan view at once.
Upstream state (issue numbers, commit pins) comes from this session's research reports: revisit at the start of W1 by re-reading upstream.
W7's question-wording half needs no page, so W7 can precede W6: revisit if W7's plan needs page changes.

Out-of-scope

Installing or vendoring html-plan or HumanLayer skills permanently.
Replacing the rendered-views convention with HTML-as-record.

Deferred questions

Q12: Which visual components ship in W6, and when? defer until W6 /planning:plan; arbiter: /planning:plan
Q13: Prose standard for plans, STE or our own writing rules? defer until W6; arbiter: USER-RESERVED
Q14: May answers given in an HTML plan view write back into PLAN.md? defer until W6; arbiter: USER-RESERVED

Execution shape: per-item PRs

Proposed work class: work-class: structural
Basis: automated intake triage; the lanes App applied this class.

Size: Large
Complexity: High
Uncertainty: Knowable
Flags: none
Blocked by: none

Understood: this is a seven-workstream program (W1–W7) to improve the planning chain using ideas from html-plan, HumanLayer rpi and Pocock's skills. It has the charter, an agreed order, and per-workstream PRs. It reads as a split parent that tracks its sub-issues, so the work lives in those sub-issues. The deferred questions (Q12–Q14) are explicitly parked until W6 and don't block triage. No likely duplicates found among the open issues.

_{Automated triage, applied by the lanes App.}

This epic does no work of its own; its needs-human label comes off once #9669 (Feature parent rule) merges. Its workstreams are sub-issues: W1 #6918, W3 #6921 and W7 #6925 are closed; W5 #6924 and W4 #6926 are now split into slices; W2 #6928 is released; W6 #6927 keeps its user-reserved questions Q13 and Q14.

This was generated by AI.

Releasing the hold. This issue is a split parent: its work lives in its sub-issues. The hold was kept until admission refused a parent with open sub-issues, and that guard is now on main: .github/scripts/intake-triage/admit.mjs:438-441 ("A split issue's work is its sub-issues' (owner Q93)"), so admission waits while any sub-issue is open. refine.mjs:292 also declines to split an issue that already has sub-issues. needs-human comes off. Nothing is re-queued: the parent stays open as the tracker until its sub-issues close.

This split was filed by hand, so it has no lanes App split record, and work-unblock's closeSplitParent will not close it on its own when the last sub-issue closes. That gap is reported to the coordinator.

Not admitted to the issue lane yet: sub-issue #6924 is open; sub-issue #6926 is open; sub-issue #6927 is open; sub-issue #6928 is open.

The latest triage verdict holds nothing: the issue is at status: ready.

Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.

Intended outcome: The epic closes as a tracker once its sub-issues W2 #6928, W4 #6926, W5 #6924 and W6 #6927 close; it needs no code change of its own.

Dependencies

#6926 (W4) is open
#6924 (W5) is split into slices, and #10067 (the html-plan trial) is open
#6927 (W6) is open and holds Q13 and Q14, which are user-reserved
#6928 (W2) is released but not yet reported closed

Related work

refactor(planning): declare the brief the spec and give each planning value one owner #6926 (related): W4 sub-issue: declare the brief the spec and give each planning value one owner
chore(planning): run the html-plan trial beside /planning:plan and record whether it changed a decision #10067 (related): W5 html-plan trial slice
feat(planning): fail a plan whose file:line citation does not exist, and stamp the commit it was checked at #10066 (related): merged W5 slice: citation check and commit stamp
feat(planning): wire the planning chain's Next routes and check the graph #7053 (related): W3 work on Next routes and the graph check, already done

Open questions

Should this epic be treated as a tracker with no lane work, so it is not refined into done-when criteria and simply closes when its last sub-issue closes?
RECOMMENDED: Yes. Keep it as a tracker, since the work lives in the sub-issues and the owner's comments say it does no work of its own. Basis: judgment
Who closes the epic when the last sub-issue closes, given that the hand-filed split has no lanes App record and closeSplitParent will not close it?
RECOMMENDED: A maintainer closes it by hand, or the coordinator gap the owner already reported is fixed first. Basis: judgment
Do Q13 (prose standard for plans) and Q14 (HTML answers writing back into PLAN.md) stay user-reserved and deferred to W6, so this epic cannot be completed unattended?
RECOMMENDED: Yes. Leave them with the user, to be answered at W6 planning. Basis: issue body, Deferred questions section

Sources read

/home/runner/work/_temp/refine-data/context.json: the issue body has no task list, and the owner's comments say the epic does no work of its own and that W1, W3 and W7 are closed
/home/runner/work/_temp/refine-data/context.json: the owner's second comment cites .github/scripts/intake-triage/admit.mjs:438-441, which makes admission wait while any sub-issue is open (I did not open that file)

_{Automated refinement by the lanes App. Answer with a comment whose first line is **Decision recorded.**.}

The triage sweep dispatched intake triage for this issue (attempt 1 of 2).

Decision recorded. The owner answered in the Refinement and Issue Triage sessions (2026-10-25), deciding the open items below on the facts:

go with whatever the facts/data/metrics + /discovery:research says and ensure we're aligned with SOLID, DRY/SSOT principles

I should only ever be in the loop ONLY when necessary (intent/vision changed, something came up during implementation that impacts trajectory/alignment, OR a high security risk) - I've covered this all before

No owner ledger (.work/*/interview-checklist.md, .work/gh-monitor-owner-decisions/) names this issue.

Parent: none needed. This is a Feature, and admission requires a Feature's parent only when it has one (.github/actions/resolve-config/admission-rules.json:5, "types-parent-if-present": ["Feature"]; .github/scripts/intake-triage/admit.mjs:444 checks the parent only when parent !== null). This issue has no parent. Its admission comment (#6917 (comment)) is a wait on open sub-issues #6924, #6926, #6927 and #6928, which is what main does for a split parent (admit.mjs:509-514).

This answers the three questions in intake's refinement (#6917 (comment)).

Is this epic a tracker with no lane work, closed when its last sub-issue closes?
Decided: Yes. The body's criteria are per workstream, and each workstream is a sub-issue: W1 docs(upstream): record html-plan, re-audit humanlayer rpi and refresh the pocock map #6918, W3 feat(planning): wire the planning chain's next routes and validate the graph #6921 and W7 feat(planning): word interview questions so yes accepts the recommendation #6925 are closed; W5 feat(planning): fail plans with missing citations and trace acceptance criteria #6924, W4 refactor(planning): declare the brief the spec and give each planning value one owner #6926, W6 feat(planning): make plans reviewable in a minute with behaviour-first summaries and code-shape views #6927 and W2 feat(knowledge): add a skill that absorbs an outside source into a docs/upstream record #6928 are open. Basis: the body's Acceptance criteria and TLDR, and the sub-issue list in the issue data.
Who closes the epic, given the hand-filed split has no lanes App record?
Decided: Issue Triage closes it as completed (R12) once every sub-issue is closed. closeSplitParent closes only a parent that carries a lanes App split record (.github/scripts/work-unblock/label-unblocked.mjs:1493). No new close path is added: the body does not ask for one.
Do Q13 and Q14 stay deferred to W6?
Decided: Yes, as the body records them: Q13 (prose standard for plans) and Q14 (HTML plan answers writing back into PLAN.md) are deferred to W6 feat(planning): make plans reviewable in a minute with behaviour-first summaries and code-shape views #6927 and are user-reserved there. This record answers neither. They gate feat(planning): make plans reviewable in a minute with behaviour-first summaries and code-shape views #6927, not this tracker. Basis: the body's Deferred questions section.

Acceptance criteria: none a lane can run. The epic does no work of its own; each workstream's criteria are its sub-issue's.

Close:

When feat(planning): fail plans with missing citations and trace acceptance criteria #6924, refactor(planning): declare the brief the spec and give each planning value one owner #6926, feat(planning): make plans reviewable in a minute with behaviour-first summaries and code-shape views #6927 and feat(knowledge): add a skill that absorbs an outside source into a docs/upstream record #6928 are all closed, Issue Triage closes this issue as completed (closes run under R12).

Navigation Menu

Repository navigation

Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917

Brief

TLDR

Goal

Constraints

Acceptance criteria

Captured assumptions

Out-of-scope

Deferred questions

2 remaining items

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Epic: improve the planning chain from html-plan, HumanLayer rpi and Pocock sources #6917

Description

Brief

TLDR

Goal

Constraints

Acceptance criteria

Captured assumptions

Out-of-scope

Deferred questions

Activity

github-actions commented on Oct 11, 2026

kyle-sexton commented on Oct 26, 2026

kyle-sexton commented on Oct 26, 2026

2 remaining items

melodic-automation-lanes commented on Oct 26, 2026

melodic-automation-lanes commented on Oct 26, 2026

melodic-automation-lanes commented on Oct 26, 2026

github-actions commented on Oct 26, 2026

kyle-sexton commented on Oct 26, 2026

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions