Skip to content

how-to-technical-writing: simple words rule and shared writing checklist - #60

Merged
GiggleLiu merged 7 commits into
mainfrom
feat/simple-words-writing-checklist
Sep 12, 2026
Merged

GiggleLiu merged 7 commits into
mainfrom
feat/simple-words-writing-checklist

Conversation

@GiggleLiu

Copy link
Copy Markdown
Member

Observation

The style guide told authors to use plain connectives, but the intended rule was broader: explain ideas with simple words rather than fancy ones. The review-paper checklist also broke the guide's own sentence rules, and the writing rubric lived in review-paper while the writing rules lived in how-to-technical-writing.

Issue

Two homes for the writing guide drift apart, and a checklist that ignores its own rules is a poor model for the prose it reviews.

Fix

  • Rename the rule to Simple words; preserve technical words and extend the examples beyond connectives ("show" over "demonstrate", "start" over "commence"). The hunt-table row, CLAUDE.md, and write-paper's summary line follow.
  • Rewrite how-to-technical-writing/SKILL.md in its own plain style.
  • Move guidelines 1–5 and 7 into skills/how-to-technical-writing/checklist.md, the single source of truth for the writing guide. skills/review-paper/checklist.md keeps only the review-process items (gate, verification, journal fit, delivery), rewritten as short sentences.
  • Update cross-references in review-paper/SKILL.md, write-paper/SKILL.md, and CLAUDE.md. Ignore .lavish/.

Verification

python3 scripts/validate_skills.py passes; pytest -q reports 247 passed.

🤖 Generated with Claude Code

https://claude.ai/code/session_018cc6n2NyTUNUDQ7LhzZDur

Rewrite the style guide in its own plain style, rename the connectives
rule to "simple words; preserve technical words", and move the writing
checklist (guidelines 1-5, 7) from review-paper into
how-to-technical-writing/checklist.md so the writing guide has one home.
review-paper/checklist.md keeps only the review-process items (gate,
verification, journal fit, delivery), rewritten in short sentences.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018cc6n2NyTUNUDQ7LhzZDur
@GiggleLiu

Copy link
Copy Markdown
Member Author

Self-review

Finding Status
Guidelines 2, 5, 7 (symbols, display math, figures) now sit in the technical-writing checklist although CLAUDE.md says notation and figure rules stay in write-paper. Accepted. The checklist header says these items apply the write-paper rulebooks; the rulebooks themselves stay in write-paper.
Guideline numbering in the two checklists is non-contiguous (1–5, 7 vs 6, 8, 9). Accepted. Numbers match the table in review-paper/SKILL.md; renumbering would break every finding that cites a guideline.
The previous branch's last commit ("update") was never in main and is folded into this PR. Fixed. Content verified identical to the old working tree; tests pass.
No test covers the new checklist.md file. Deferred. Structural tests check SKILL.md frontmatter only; a checklist test adds little.

GiggleLiu and others added 3 commits September 10, 2026 20:23
…t skills

Delete test, trust the structure, define at the point of need, pointer
not restatement, pay every promise, no drifting duplicates, and set up
before calculating. Each has a hunt row and a checklist item.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018cc6n2NyTUNUDQ7LhzZDur
@GiggleLiu
GiggleLiu requested a review from isPANN September 10, 2026 12:30
Comment thread skills/how-to-technical-writing/checklist.md Outdated
Comment thread skills/how-to-technical-writing/checklist.md Outdated
@GiggleLiu
GiggleLiu merged commit 905ea3e into main Sep 12, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants