Skip to content

Fix base:writing-client-updates: add pre-draft fact-check checklist · claude-toolkit - #39

Open
dev-refact wants to merge 2 commits into
mainfrom
job/task_1217817153379702-a962d84292-claude-toolkit
Open

Fix base:writing-client-updates: add pre-draft fact-check checklist · claude-toolkit#39
dev-refact wants to merge 2 commits into
mainfrom
job/task_1217817153379702-a962d84292-claude-toolkit

Conversation

@dev-refact

Copy link
Copy Markdown

Task done. base:writing-client-updatesv1.2.0.

Where the work landed. The task sits on the Skill Analyzer board, so open-project --task gave me skill-radar — which holds no catalog skill files (its toolkit clone is read-only by design). The skill lives in refactco/claude-toolkit, which I opened as well. The PR is on claude-toolkit; skill-radar is untouched.

All four acceptance criteria are in. A new ## Pre-draft fact check section in references/writing-client-updates.md, with a step 3 in SKILL.md that runs it before drafting:

  • Recipient confirmed from the project docs, never from a chat message, commit, or email address; ask rather than guess.
  • Facts-only drafting. Every fact, name, number, date, URL, quote and clause must appear in the source; anything else is cut or marked as an assumption in-sentence. Never attribute a claim to someone who didn't make it. Status words count as facts (an open PR is open).
  • A client-requested vs internally-discovered check before the opening is chosen, with a worked example of each, plus a check on whether the message is even a client update.

On the collision check (criterion 4): no collision, and it's recorded in the changelog. The ~120-word ceiling and the merge/deploy guard from 1.1.0 are unchanged as steps 5 and 6. The fact check is a gate on your notes, not a section of the message, so it costs the draft nothing, and it caps assumption-marking at a few words — a claim needing a paragraph of hedging gets cut instead. It removes rewrite passes rather than adding length.

Also shipped: the per-skill CHANGELOG entry with the four verified quotes and the radar:expectation marker (baseline 3 → target 1, 4w); pack 1.11.1 → 1.12.0 and marketplace 2.16.0 → 2.17.0 with sync-codex.mjs regenerating the derived catalogs. sync-codex --check, check-plugins.py and node --test tests/*.test.mjs (64 tests) all pass. I also repaired SKILL.md steps 4 and 5, which had been running together on one line since 1.1.0 — the merge/deploy guard was buried mid-sentence.

Two things I flagged rather than decided, proposed as a comment on the task:

  • The version lineage is unresolved and it decides whether this counts as shipped. The catalog and skill file said 1.1.0 so I bumped to 1.2.0, but task 1217329825906199 records real sessions running v1.6.1 and v1.8.0. If sessions load that lineage, the radar will report this fix as never shipped. Worth settling before the W38 re-count.
  • Scope. I folded in the SR-2026W37-06 item the radar explicitly routed here (verify every claim in a referenced source doc, not just the first named). Left to the sibling task: the ~120-word measure-and-trim step and the third format branch for internal ticket updates.

Memory: one knowledge doc, refact-os/knowledge/shipping-a-catalog-skill-fix.md — the board/repo split, what one fix touches, and why the version bump is what makes a fix measurable. The gap itself was already tracked in the W37 radar concern entry, so I didn't duplicate it.

In the room: Refact Engineering (joined from a terminal 14:38 UTC).

Refs asana#1217817153379702

… claude-toolkit

Refs asana#1217817153379702

Refact-Job: task_1217817153379702-a962d84292
Comment thread plugins/base/skills/writing-client-updates/references/writing-client-updates.md Outdated
Refs asana#1217817153379702

Refact-Job: task_1217817153379702-a962d84292
@dev-refact

Copy link
Copy Markdown
Author

Updated from the room. In the room: Refact Engineering (joined from a terminal 14:38 UTC, took over in the app 14:47 UTC).

4. Draft the update in the correct format for the channel (full 7-part structure for email; headline-first short form for Slack).
5. Never state a merge, deploy, or release status (e.g. "merged to stage", "promoted to production", "deployed") unless a corresponding tool action — an actual merge or deploy — was executed and observed in this session. If only a PR was opened, say exactly that; do not describe it as merged or released.
6. Keep the first draft short: aim for roughly half a screen (about 120 words for email, 40 for Slack). Match length to the situation's complexity so the first draft does not need to be rewritten shorter.
7. Offer to tighten or adjust tone before the user sends it.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use simpler english words for this item

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dev-refact do this bro

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants