guideline-writing

Name: guideline-writing
Author: alfadur7

56stars10forks

How to install guideline-writing?

alfadur7/llm-wiki-newsroom/guideline-writing

$npx -y skills add alfadur7/llm-wiki-newsroom --skill guideline-writing

Installs into the current project.

Summary

Guideline-authoring craft for instruction SoTs (.claude/ guides, CLAUDE.md, plan files) — operative rules vs recital, MUST/SHOULD/MAY force tiers, pruning, bloat control, blind review protocol, deliberation-narrative ban. Use when writing, editing, or reviewing an agent instructi

Files · 1

View on GitHub

SKILL.md

1	# Guideline Writing
2
3	Craft for authoring the instruction layer itself — the `.claude/` guide SoTs, `CLAUDE.md`, and plan files. Content pages have the four content-craft skills (jrn·con·enc·cit); this skill is their counterpart for the meta layer. Dotted IDs: `gdl.*` ([criteria.json](criteria.json)); the deterministic detectors live in [checks.py](checks.py) and run inside `python tools/lint.py meta`.
4
5	## Operative Rule vs Recital
6
7	Every sentence in a guideline is one of two kinds, and only the first belongs in the body:
8
9	- Operative rule — tells the reader what to do, when, and how to tell they did it right. Test: delete the sentence; if an executor could now act differently and still believe they complied, the sentence was operative.
10	- Recital — explains how the rule came to be: options weighed, benchmarks absorbed, incidents survived, dates adopted. Recitals are history; history's SoT is `log.md` (append-only). A recital in the body is deliberation narrative — the central antipattern this skill exists to prevent.
11
12	A failure mode earns at most one line in the body — the concrete trigger the rule guards against, stated as a present-tense condition ("a partial edit bumps only the date and masks body staleness"), never as a war story ("after the 05-20 incident we decided…"). The story goes to `log.md`.
13
14	## Force Tiers — MUST / SHOULD / MAY
15
16	State every rule at exactly one force tier, and make the tier visible in the wording:
17
18	\| Tier \| Wording \| Reader's obligation \| Verification \|
19	\|---\|---\|---\|---\|
20	\| MUST \| "is mandatory" · "never" · imperative \| no discretion; violating it is a defect \| lint-gate or blocking hook where possible \|
21	\| SHOULD \| "by default" · "prefer" · "unless" \| may deviate with a stated reason \| advisory hook · review lens \|
22	\| MAY \| "can" · "optionally" \| pure permission \| none \|
23
24	Antipattern: hedged MUSTs ("should generally always…") and decorated MAYs ("it is strongly recommended to consider…"). If you cannot pick the tier, you have not finished deciding the rule — finish deciding before writing.
25
26	## Pruning
27
28	A guideline corpus only stays executable if rules leave at the same rate reality invalidates them:
29
30	- Prune-or-enforce: a rule that is neither checked (lint·hook·review lens) nor followed is dead weight — either wire an enforcement surface or delete it. Keeping it "as documentation" is the recital antipattern wearing a rule's clothes.
31	- Deprecation signal: a detector or lens with 0 surfacings across 5 consecutive batches is a deletion candidate (mirrors the desk promotion loop's burn criteria).
32	- Delete whole units: prune at the bullet/section level, not by shaving words — a half-pruned rule reads as a weaker rule, not a shorter one.
33
34	## Bloat Control
35
36	Absorb into an existing section, table, or matrix by default; create something new only after proving no matching pattern exists.
37
38	5-step self-check (mandatory just before finishing a guideline or plan edit):
39	1. New section/table/matrix vs a one-line absorption into an existing section — absorb by default
40	2. Zero copies of another SoT's table/matrix — replace with a cross-reference
41	3. Zero new Risk/invariant/caveat sections by default — prefer attaching a qualifier to an existing section
42	4. When the changed lines ≥ 50, a mandatory minimum-edit re-review
43	5. Read the full context of each changed file before declaring the edit done
44
45	4 red flags (a single hit forces the 5-step re-review):
46	- ≥ 2 new sections added
47	- ≥ 50 changed lines
48	- a new table or matrix added
49	- the same information already exists in another SoT
50
51	File naming (T1 prescriptive default): a new memory/policy/hook file takes an imperative form — `no_X` · `X_to_Y` · `X_not_Y`. Descriptive names (`_voice` · `_posture`) require two-step inference on recall and match utterance patterns weakly.
52
53	## Blind Review Protocol
54
55	A guideline edit is reviewed by a reader who did not write it and does not know the deliberation behind it. In this project it runs as rung 3 of the Guideline Verification Ladder (`.claude/agents/editor-in-chief.md`); the protocol itself is project-agnostic:
56
57	1. Input = the diff only — no chat context, no rationale memo. The reviewer sees exactly what a future executor will see.
58	2. Classification reply is mandatory: the reviewer returns, per hunk, a two-way verdict — substantive (an executor would act differently after this change) or invariant (wording/structure only, behavior unchanged) — plus any defects found against this skill's criteria.
59	3. **Defect form

People who liked this also viewed

6 picks

Type

guideline-writing

56stars10forks

View on GitHub

How to install guideline-writing?

alfadur7/llm-wiki-newsroom/guideline-writing

$npx -y skills add alfadur7/llm-wiki-newsroom --skill guideline-writing

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Guideline Writing
2
3	Craft for authoring the instruction layer itself — the `.claude/` guide SoTs, `CLAUDE.md`, and plan files. Content pages have the four content-craft skills (jrn·con·enc·cit); this skill is their counterpart for the meta layer. Dotted IDs: `gdl.*` ([criteria.json](criteria.json)); the deterministic detectors live in [checks.py](checks.py) and run inside `python tools/lint.py meta`.
4
5	## Operative Rule vs Recital
6
7	Every sentence in a guideline is one of two kinds, and only the first belongs in the body:
8
9	- Operative rule — tells the reader what to do, when, and how to tell they did it right. Test: delete the sentence; if an executor could now act differently and still believe they complied, the sentence was operative.
10	- Recital — explains how the rule came to be: options weighed, benchmarks absorbed, incidents survived, dates adopted. Recitals are history; history's SoT is `log.md` (append-only). A recital in the body is deliberation narrative — the central antipattern this skill exists to prevent.
11
12	A failure mode earns at most one line in the body — the concrete trigger the rule guards against, stated as a present-tense condition ("a partial edit bumps only the date and masks body staleness"), never as a war story ("after the 05-20 incident we decided…"). The story goes to `log.md`.
13
14	## Force Tiers — MUST / SHOULD / MAY
15
16	State every rule at exactly one force tier, and make the tier visible in the wording:
17
18	\| Tier \| Wording \| Reader's obligation \| Verification \|
19	\|---\|---\|---\|---\|
20	\| MUST \| "is mandatory" · "never" · imperative \| no discretion; violating it is a defect \| lint-gate or blocking hook where possible \|
21	\| SHOULD \| "by default" · "prefer" · "unless" \| may deviate with a stated reason \| advisory hook · review lens \|
22	\| MAY \| "can" · "optionally" \| pure permission \| none \|
23
24	Antipattern: hedged MUSTs ("should generally always…") and decorated MAYs ("it is strongly recommended to consider…"). If you cannot pick the tier, you have not finished deciding the rule — finish deciding before writing.
25
26	## Pruning
27
28	A guideline corpus only stays executable if rules leave at the same rate reality invalidates them:
29
30	- Prune-or-enforce: a rule that is neither checked (lint·hook·review lens) nor followed is dead weight — either wire an enforcement surface or delete it. Keeping it "as documentation" is the recital antipattern wearing a rule's clothes.
31	- Deprecation signal: a detector or lens with 0 surfacings across 5 consecutive batches is a deletion candidate (mirrors the desk promotion loop's burn criteria).
32	- Delete whole units: prune at the bullet/section level, not by shaving words — a half-pruned rule reads as a weaker rule, not a shorter one.
33
34	## Bloat Control
35
36	Absorb into an existing section, table, or matrix by default; create something new only after proving no matching pattern exists.
37
38	5-step self-check (mandatory just before finishing a guideline or plan edit):
39	1. New section/table/matrix vs a one-line absorption into an existing section — absorb by default
40	2. Zero copies of another SoT's table/matrix — replace with a cross-reference
41	3. Zero new Risk/invariant/caveat sections by default — prefer attaching a qualifier to an existing section
42	4. When the changed lines ≥ 50, a mandatory minimum-edit re-review
43	5. Read the full context of each changed file before declaring the edit done
44
45	4 red flags (a single hit forces the 5-step re-review):
46	- ≥ 2 new sections added
47	- ≥ 50 changed lines
48	- a new table or matrix added
49	- the same information already exists in another SoT
50
51	File naming (T1 prescriptive default): a new memory/policy/hook file takes an imperative form — `no_X` · `X_to_Y` · `X_not_Y`. Descriptive names (`_voice` · `_posture`) require two-step inference on recall and match utterance patterns weakly.
52
53	## Blind Review Protocol
54
55	A guideline edit is reviewed by a reader who did not write it and does not know the deliberation behind it. In this project it runs as rung 3 of the Guideline Verification Ladder (`.claude/agents/editor-in-chief.md`); the protocol itself is project-agnostic:
56
57	1. Input = the diff only — no chat context, no rationale memo. The reviewer sees exactly what a future executor will see.
58	2. Classification reply is mandatory: the reviewer returns, per hunk, a two-way verdict — substantive (an executor would act differently after this change) or invariant (wording/structure only, behavior unchanged) — plus any defects found against this skill's criteria.
59	3. **Defect form

People who liked this also viewed

6 picks

Type