feat(adhd): add clarify skill — faithfully restructure a dense artifact#1073
Conversation
Add /adhd:digest: an on-demand, one-shot reshape of a dense, decision-heavy message already on screen (default target: the previous assistant response; explicit target overrides). Restructures faithfully — chunks one-decision-at-a- time, defines the session's own jargon, surfaces what the reader must decide — under hard fidelity rules: operative terms quoted verbatim, original item numbers kept as back-links, omissions listed explicitly, and a lens-not-replacement closing line. Changes STRUCTURE, never altitude. Artifact-forward: big/decision-dense content renders an HTML decision table (item | recommendation | alternative | what-you're-deciding, rows numbered so terminal answers map back), honoring the Artifact contract via artifact-design; degrades to a local HTML file, then structured terminal markdown. Resolve the CRITICAL trigger collision with education:explain (both auto-fire and default to the previous response) by writing the altitude-vs-structure decision rule into BOTH descriptions with disjoint triggers — explain preserves all 7 of its trigger keywords. Add an in-plugin boundary line to adhd:shape (standing posture vs one-shot reshape). adhd 0.1.0 -> 0.2.0 (new skill); education 0.5.1 -> 0.5.2 (explain routing boundary). Catalog regenerated. Name is provisional pending a blind naming pass and human confirmation. Closes #1070 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
|
Claude encountered an error after 1s —— View job I'll analyze this and get back to you. |
|
Warning Automated review did not complete — this is an infrastructure failure, not a review verdict. Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."
Re-running the job, or pushing a new commit, will retry the review. |
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
|
Warning Automated security review did not complete — this is an infrastructure failure, not a review verdict. Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."
Re-running the job, or pushing a new commit, will retry the review. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cf761fb547
ℹ️ 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".
Kyle locked the name /adhd:clarify: the reflex moment is "make this clear" at a jargon wall, and clarify carries faithfulness in the word (make clear without changing substance) — chosen over digest/untangle/decode (imply the text is a mess) and the blind-lens picks restructure/chunk (segmentation-only). Pure rename + prose reconciliation; behavior, fidelity rules, artifact-forward ladder, and the altitude-vs-structure boundary are unchanged. Skill dir and name, evals skill_name, all adhd:digest references (explain + shape boundary sentences, plugin.json, both changelogs, README), and the plugin keyword move to clarify. Catalog regenerated. The trigger phrase "help me digest this" is kept as a real user reflex. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
|
Claude encountered an error after 1s —— View job I'll analyze this and get back to you. |
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
- Local HTML fallback: pin the destination to ${CLAUDE_PLUGIN_DATA} or an OS
temp path (a clarified view is transient generated state) so it never dirties
the consumer's repository tree; drop to terminal markdown if no writable
location exists.
- artifact-design reference: presence-gate it ("when it is available") with a
fallback to the Artifact contract essentials (self-contained, theme-aware,
title/description/favicon), per the marketplace's guard-and-fallback policy
for optional collaborators, rather than a bare mandatory load.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e1b413c18d
ℹ️ 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".
Third Codex P2: copying operative terms verbatim into HTML corrupts code-like text (<dialog>, A && B) and can execute markup when the clarified artifact is untrusted. Require treating copied source text as text content / HTML-escaping it in the artifact and local-file media — this is what keeps the verbatim fidelity rule true in the rendered page and closes the injection vector — and backticking code-like terms in the terminal-markdown medium. Tightened intro and a redundant gotcha to stay within the 200-line soft target. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9e5d7af5ed
ℹ️ 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".
| 2. **Ground it, don't recall it.** Re-read the actual artifact this turn — the | ||
| message just sent, in full. Working from your memory of it instead of its text |
There was a problem hiding this comment.
When the user passes an explicit earlier target, e.g. /adhd:clarify the design memo you wrote three messages ago, this grounding step tells the agent to re-read “the message just sent” instead of the target selected in step 1. That can make the skill clarify the invocation text or otherwise ignore the explicit override, contradicting the intended behavior for named earlier artifacts; anchor this step to the resolved target’s full text rather than the latest message.
Useful? React with 👍 / 👎.
Closes #1070
Summary
Adds
/adhd:clarify: an on-demand, one-shot reshape of a dense, decision-heavy message already on screen so a reader (especially one offloading working memory) can act on it. It restructures faithfully — chunks the content one-decision-at-a-time, defines the session's own jargon, and surfaces exactly what must be decided — and it renders an HTML decision table for big content. This is the consumer-side counterpart to the producer-side interview-format levers already shipped (planning PR #1048); where those fix the flagship producer, this rescues any dense artifact reactively.The core discipline: change STRUCTURE, never altitude. Lowering the reading level (plain words / ELI5 / lossy simplification) is
education:explain's lane; this holds precision and reading level fixed and only reorganizes — it makes the same content clear without simplifying it.Fix
plugins/adhd/skills/clarify/(SKILL.md + evals.json). Default target is the previous assistant response (anaphora); an explicit target overrides.item | recommendation | alternative | what-you're-deciding, rows numbered so terminal answers map back; honors the Artifact tool contract via theartifact-designskill; degrades to a local HTML file, then structured terminal markdown, when the Artifact surface is unavailable. Static table — no runtime capabilities declared.education:explain(both auto-fire and default to the previous response): the altitude-vs-structure decision rule is written into both descriptions with disjoint triggers, so routing is on intent, not overlapping phrases. All 7 of explain's trigger keywords are preserved (verified by skill-quality's keyword-preservation check).adhd:shape(standing session posture vs one-shot reshape); its 5 trigger keywords preserved.adhd0.1.0 -> 0.2.0 (new skill),education0.5.1 -> 0.5.2 (explain routing boundary). Changelogs updated; root catalog regenerated; adhd README updated for the second skill.Naming
Name
clarifyis human-locked (chosen over digest/untangle/decode and the blind-lens picks restructure/chunk — clarify carries faithfulness in the word: make clear without changing substance). The trigger phrase "help me digest this" is kept as a genuine user reflex.One PR, not two (deliberate)
The two-plugin touch ships as one PR because the mutual-exclusion boundary is atomic: splitting it opens a window where either
explainauto-fires onclarify's triggers (adhd-first) orexplain's description references a not-yet-existent boundary (education-first). The two descriptions are a matched pair implementing one disjoint-trigger contract.Verification
All run locally on the branch (post-rename):
skill-qualitycheck —clarifyPASS (0 errors, 0 warnings; 189/500 lines, desc 1058/1536 chars);explainPASS (all 7 trigger phrases preserved);shapePASS (all 5 preserved; one pre-existing Gotchas-surface WARN, not introduced here).claude plugin validate—adhdandeducationboth pass.check-changelog-parity.sh --check-bump origin/main— both bumped plugins have matching## [<version>]entries.generate-catalog.mjs --check— catalog in sync.validate-plugin-contracts.mjs— pass.check-skill-leaf-names.sh --check—clarifyis a unique leaf, no collision.check-skill-portability.sh origin/main— no coupling tokens.markdownlint-cli2on changed docs — 0 errors.clarifyevals.json— valid against the bundled schema (5 cases).Related