[fast-path] docs(ask-user): route talk-to-user via gist + htmlpreview, require visual content - #449
[fast-path] docs(ask-user): route talk-to-user via gist + htmlpreview, require visual content#449LiuShiyuMath wants to merge 2 commits into
Conversation
… file:// flow When agent needs to talk to users, the canonical flow is now: 1. haiku subagent writes self-contained visual HTML (cards/chips/SVG/ASCII art - no raw boring text) 2. gh gist create --public uploads to the maintainer's own gist 3. open -a 'Google Chrome' "https://htmlpreview.github.io/?<raw-gist-url>" Rationale: cross-device access, persistent audit trail, zero extra infra, reuses VISUAL-PROOF-FORMAT.md hosting convention, avoids Chrome file:// Clipboard API restrictions.
…alk to users' trigger
Anchor block now:
- Adds 'what should we do everything we need to talk to users' as canonical trigger
- Requires haiku subagent → gh gist create --public → htmlpreview.github.io URL → Chrome
- Bans raw-boring-text plain forms; requires >=3 of {cards, chips, color sections, SVG, metric cards, ASCII art}
- Documents the 5 fallback cases (no gh auth, headless, trivial y/n, user opt-out, in-app)
- Notes /tmp is now upload source not direct file:// target
Aligns the talk-to-user UX with VISUAL-PROOF-FORMAT.md hosting convention.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 14223655dd
ℹ️ 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".
| 3. 在主 session 里调 `open -a "Google Chrome" /tmp/ask-<topic>-<timestamp>.html`（Linux 用 `xdg-open`、Windows 用 `start chrome`）把页面弹给用户。 | ||
| 4. 用户在浏览器里点选 / 填写 → 回到 agent 会话把选择口述或粘贴回来 → agent 继续推进。 | ||
| 1. **派 haiku subagent** 写一个 self-contained **visual** HTML 文件（cards / chips / color-coded sections / 内联 SVG / ASCII art 框图），落地到 `/tmp/ask-<slug>-<unix-ts>.html` 作为本地暂存。**不**允许只写「label + radio + button」的朴素表单——HTML 必须带视觉层次（最少：分区底色 + chip 圆角标签 + 中间分隔线 + 颜色对比的选中态）。 | ||
| 2. **托管到 maintainer 自己的 GitHub Gist**：`gh gist create --public /tmp/ask-<slug>-<unix-ts>.html`，拿到 gist raw blob URL（形如 `https://gist.githubusercontent.com/<you>/<id>/raw/<file>.html`）。 |
There was a problem hiding this comment.
This change mandates gh gist create --public for every user-question page, which makes the content publicly listed even when it may contain unreleased plans, internal repo details, or user-provided notes. The gh gist create CLI defaults to secret gists, and secret gist URLs are still shareable across devices, so forcing --public adds data-exposure risk without being required for the cross-device workflow described here.
Useful? React with 👍 / 👎.
1 participant
Summary
Closes #448.
[fast-path]perdocs/FAST-PATH-PR.md(docs-only, single-file rule update, no new code paths, no business-logic / public-API / DB-schema / hook-protocol changes).Update
docs/ASK-USER-VIA-HTML.md+CLAUDE.mdanchor block so every agent→user "talk to user" moment routes through:<form>+ radio + button is banned)gh gist create --public /tmp/ask-<slug>-<ts>.htmluploads to the maintainer's own GitHub Gistopen -a "Google Chrome" "https://htmlpreview.github.io/?<raw-gist-url>"pops the page in Chrome — any device / phone / second machine can open the same public URLSupersedes the prior
/tmpfile:// flow (kept only as the upload source). Aligns talk-to-user UX with the existingdocs/VISUAL-PROOF-FORMAT.md § HostingGist + htmlpreview convention.Also adds "what should we do everything we need to talk to users" as a canonical English trigger phrase on the anchor block, plus the matching Chinese variants ("需要跟用户沟通 / 提问 / 收集决策时怎么做").
Files changed
docs/ASK-USER-VIA-HTML.md— full rewrite of TL;DR, STEP 1-4, validation, and "与现有规则的关系" sections; 123 lines (under the 200-line cap).CLAUDE.md— anchor block at line 137 rewritten (single line in the table-of-anchors).Self-dogfood note
This PR does not introduce a new verbatim canned-answer anchor with strict substring-grep harness — the existing rule had no verbatim canned answer, and this PR keeps it that way. The new "what should we do everything we need to talk to users" phrase is listed as a trigger hint, not a verbatim grep contract. That keeps this PR inside the
fast-pathcarve-out (perdocs/FAST-PATH-PR.mdself-dogfood clause: only new verbatim canned-anchor cards require full FIXEDFLOW grill; rule updates with soft trigger hints stay in docs-update fast-path).Test plan
/reviewpasses one turn (ADR-0007 authoritative POSTPR gate)wc -l docs/ASK-USER-VIA-HTML.md< 200 (currently 123)Verification (judge-harness style)
Anchor-block lint:
Risk
Low. Docs-only. The rule it updates is agent-prompt guidance — no runtime code reads this file at execution time. Worst case: an agent reads stale guidance and still falls back to
/tmpfile:// (documented as fallback case (a) "no gh auth").