@bompus/house-rules 0.0.0-stage → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/CONTRIBUTING.md +54 -0
  2. package/LICENSE +21 -0
  3. package/README.md +347 -2
  4. package/THIRD_PARTY_NOTICES.md +188 -0
  5. package/compose.mjs +119 -0
  6. package/composition.mjs +353 -0
  7. package/config-view.mjs +194 -0
  8. package/config.mjs +320 -0
  9. package/docs/assets/banner-dark.png +0 -0
  10. package/docs/assets/banner-light.png +0 -0
  11. package/docs/assets/overview.png +0 -0
  12. package/docs/configuration.md +193 -0
  13. package/docs/npm-release.md +45 -0
  14. package/docs/skill-names.md +50 -0
  15. package/examples/person/house-rules.json +15 -0
  16. package/examples/person/rules/10-tooling.md +8 -0
  17. package/examples/person/rules/20-reporting.md +9 -0
  18. package/examples/project/AGENTS.md +18 -0
  19. package/package.json +40 -4
  20. package/rule-references.mjs +91 -0
  21. package/rules/core.md +431 -0
  22. package/rules/modifiers/coded-offers.md +40 -0
  23. package/rules/modifiers/effort-estimates.md +41 -0
  24. package/rules/modifiers/land-when-done.md +12 -0
  25. package/rules/modifiers/low-quota-handoff.md +19 -0
  26. package/rules/modifiers/multi-agent.md +34 -0
  27. package/rules/modifiers/no-attribution.md +10 -0
  28. package/rules/modifiers/plan-files.md +50 -0
  29. package/rules/modifiers/question-cards.md +48 -0
  30. package/rules/modifiers/release-batching.md +13 -0
  31. package/rules/modifiers/scratch-on-disk.md +15 -0
  32. package/rules/modifiers/shared-host-load.md +48 -0
  33. package/rules/modifiers/solo-operator.md +13 -0
  34. package/rules/modifiers/squash-landing.md +22 -0
  35. package/rules/modifiers/swarmail.md +12 -0
  36. package/rules/references/github-actions.md +45 -0
  37. package/rules/references/landing.md +39 -0
  38. package/rules/references/multi-agent.md +47 -0
  39. package/rules/references/release-batching.md +43 -0
  40. package/rules/references/squash-landing.md +44 -0
  41. package/setup.mjs +375 -0
  42. package/skills/hr-agent-guidance-audit/LICENSE +21 -0
  43. package/skills/hr-agent-guidance-audit/SKILL.md +86 -0
  44. package/skills/hr-agent-guidance-audit/agents/openai.yaml +2 -0
  45. package/skills/hr-agent-guidance-audit/references/records-and-lessons.md +60 -0
  46. package/skills/hr-agent-guidance-refresh/LICENSE +21 -0
  47. package/skills/hr-agent-guidance-refresh/SKILL.md +68 -0
  48. package/skills/hr-agent-guidance-refresh/agents/openai.yaml +2 -0
  49. package/skills/hr-agent-guidance-refresh/references/verification.md +47 -0
  50. package/skills/hr-api-exposure-check/SKILL.md +159 -0
  51. package/skills/hr-api-exposure-check/agents/openai.yaml +3 -0
  52. package/skills/hr-audit-choices/SKILL.md +67 -0
  53. package/skills/hr-audit-choices/agents/openai.yaml +2 -0
  54. package/skills/hr-benchmarking/NOTICE.md +36 -0
  55. package/skills/hr-benchmarking/SKILL.md +316 -0
  56. package/skills/hr-benchmarking/agents/openai.yaml +2 -0
  57. package/skills/hr-benchmarking/references/javascript.md +17 -0
  58. package/skills/hr-benchmarking/references/priority-findings-20261006.md +115 -0
  59. package/skills/hr-benchmarking/references/tools.md +160 -0
  60. package/skills/hr-benchmarking/scripts/process-attribution.ps1 +20 -0
  61. package/skills/hr-benchmarking/scripts/process-attribution.py +107 -0
  62. package/skills/hr-better-accessibility/LICENSE +22 -0
  63. package/skills/hr-better-accessibility/NOTICE.md +46 -0
  64. package/skills/hr-better-accessibility/SKILL.md +119 -0
  65. package/skills/hr-better-accessibility/agents/openai.yaml +3 -0
  66. package/skills/hr-better-accessibility/focus-and-keyboard.md +130 -0
  67. package/skills/hr-better-accessibility/forms.md +82 -0
  68. package/skills/hr-better-accessibility/hit-areas.md +98 -0
  69. package/skills/hr-better-accessibility/motion-and-zoom.md +81 -0
  70. package/skills/hr-better-accessibility/screen-readers.md +101 -0
  71. package/skills/hr-better-accessibility/semantics-and-aria.md +84 -0
  72. package/skills/hr-better-colors/LICENSE +21 -0
  73. package/skills/hr-better-colors/NOTICE.md +37 -0
  74. package/skills/hr-better-colors/SKILL.md +114 -0
  75. package/skills/hr-better-colors/agents/openai.yaml +3 -0
  76. package/skills/hr-better-colors/color-formats.md +90 -0
  77. package/skills/hr-better-colors/color-usage.md +140 -0
  78. package/skills/hr-better-colors/contrast.md +80 -0
  79. package/skills/hr-better-colors/palette-generation.md +104 -0
  80. package/skills/hr-better-colors/palette-structure.md +76 -0
  81. package/skills/hr-better-colors/token-naming.md +97 -0
  82. package/skills/hr-better-layout/LICENSE +22 -0
  83. package/skills/hr-better-layout/NOTICE.md +48 -0
  84. package/skills/hr-better-layout/SKILL.md +92 -0
  85. package/skills/hr-better-layout/agents/openai.yaml +3 -0
  86. package/skills/hr-better-layout/grouping-and-alignment.md +144 -0
  87. package/skills/hr-better-layout/spacing-and-adaptivity.md +215 -0
  88. package/skills/hr-better-typography/LICENSE +22 -0
  89. package/skills/hr-better-typography/NOTICE.md +46 -0
  90. package/skills/hr-better-typography/SKILL.md +172 -0
  91. package/skills/hr-better-typography/agents/openai.yaml +3 -0
  92. package/skills/hr-better-typography/choosing-fonts.md +69 -0
  93. package/skills/hr-better-typography/css-cheat-sheet.md +65 -0
  94. package/skills/hr-better-typography/details-and-accessibility.md +119 -0
  95. package/skills/hr-better-typography/spacing-and-sizing.md +131 -0
  96. package/skills/hr-better-typography/variable-fonts-and-opentype.md +105 -0
  97. package/skills/hr-better-typography/wrapping-and-punctuation.md +57 -0
  98. package/skills/hr-better-writing/LICENSE +22 -0
  99. package/skills/hr-better-writing/NOTICE.md +46 -0
  100. package/skills/hr-better-writing/SKILL.md +122 -0
  101. package/skills/hr-better-writing/agents/openai.yaml +3 -0
  102. package/skills/hr-change-impact/SKILL.md +113 -0
  103. package/skills/hr-change-impact/agents/openai.yaml +5 -0
  104. package/skills/hr-code-review/LICENSE +21 -0
  105. package/skills/hr-code-review/NOTICE.md +26 -0
  106. package/skills/hr-code-review/SKILL.md +147 -0
  107. package/skills/hr-code-review/agents/openai.yaml +3 -0
  108. package/skills/hr-code-review/references/evidence.md +57 -0
  109. package/skills/hr-design-exploration/SKILL.md +82 -0
  110. package/skills/hr-design-exploration/agents/openai.yaml +4 -0
  111. package/skills/hr-diagnosing-bugs/NOTICE.md +45 -0
  112. package/skills/hr-diagnosing-bugs/SKILL.md +108 -0
  113. package/skills/hr-diagnosing-bugs/agents/openai.yaml +3 -0
  114. package/skills/hr-diagnosing-bugs/references/reporting.md +72 -0
  115. package/skills/hr-explain-code/NOTICE.md +37 -0
  116. package/skills/hr-explain-code/SKILL.md +110 -0
  117. package/skills/hr-explain-code/agents/openai.yaml +5 -0
  118. package/skills/hr-explain-code/references/helper-brief.md +39 -0
  119. package/skills/hr-extract-shared-steps/SKILL.md +134 -0
  120. package/skills/hr-extract-shared-steps/agents/openai.yaml +3 -0
  121. package/skills/hr-handoff/SKILL.md +91 -0
  122. package/skills/hr-handoff/agents/openai.yaml +5 -0
  123. package/skills/hr-handoff/assets/ledger.example.json +10 -0
  124. package/skills/hr-handoff/assets/receipt.example.json +76 -0
  125. package/skills/hr-handoff/assets/source.example.json +20 -0
  126. package/skills/hr-handoff/references/reconciliation.md +105 -0
  127. package/skills/hr-handoff/scripts/check-reconciliation.mjs +282 -0
  128. package/skills/hr-house-rules-setup/SKILL.md +100 -0
  129. package/skills/hr-house-rules-setup/agents/openai.yaml +5 -0
  130. package/skills/hr-issue-tracker-setup/SKILL.md +49 -0
  131. package/skills/hr-issue-tracker-setup/agents/openai.yaml +5 -0
  132. package/skills/hr-lean-plan/SKILL.md +142 -0
  133. package/skills/hr-lean-plan/agents/openai.yaml +5 -0
  134. package/skills/hr-maintainability-review/SKILL.md +176 -0
  135. package/skills/hr-maintainability-review/agents/openai.yaml +5 -0
  136. package/skills/hr-manual-qa/NOTICE.md +36 -0
  137. package/skills/hr-manual-qa/SKILL.md +37 -0
  138. package/skills/hr-manual-qa/agents/openai.yaml +3 -0
  139. package/skills/hr-navigation-retro/LICENSE +21 -0
  140. package/skills/hr-navigation-retro/NOTICE.md +5 -0
  141. package/skills/hr-navigation-retro/SKILL.md +86 -0
  142. package/skills/hr-navigation-retro/agents/openai.yaml +4 -0
  143. package/skills/hr-navigation-retro/references/inputs.md +67 -0
  144. package/skills/hr-navigation-retro/scripts/retro.py +552 -0
  145. package/skills/hr-navigation-retro/scripts/transcripts.py +205 -0
  146. package/skills/hr-ordering-tests/SKILL.md +51 -0
  147. package/skills/hr-ordering-tests/agents/openai.yaml +2 -0
  148. package/skills/hr-plain-prose/SKILL.md +261 -0
  149. package/skills/hr-plain-prose/agents/openai.yaml +3 -0
  150. package/skills/hr-plain-prose/scripts/check.mjs +331 -0
  151. package/skills/hr-pr-followup/LICENSE +21 -0
  152. package/skills/hr-pr-followup/NOTICE.md +9 -0
  153. package/skills/hr-pr-followup/SKILL.md +71 -0
  154. package/skills/hr-pr-followup/agents/openai.yaml +2 -0
  155. package/skills/hr-pr-followup/references/review-helpers.md +90 -0
  156. package/skills/hr-pr-followup/scripts/check-pr-review.ts +510 -0
  157. package/skills/hr-pr-followup/scripts/resolve-pr-thread.ts +219 -0
  158. package/skills/hr-progress-report/SKILL.md +49 -0
  159. package/skills/hr-progress-report/agents/openai.yaml +5 -0
  160. package/skills/hr-read-reddit/SKILL.md +44 -0
  161. package/skills/hr-read-reddit/agents/openai.yaml +2 -0
  162. package/skills/hr-read-reddit/scripts/reddit.ts +252 -0
  163. package/skills/hr-read-x-links/SKILL.md +42 -0
  164. package/skills/hr-read-x-links/agents/openai.yaml +2 -0
  165. package/skills/hr-read-x-links/scripts/x-post.ts +264 -0
  166. package/skills/hr-split-to-prs/LICENSE +21 -0
  167. package/skills/hr-split-to-prs/NOTICE.md +9 -0
  168. package/skills/hr-split-to-prs/SKILL.md +61 -0
  169. package/skills/hr-split-to-prs/agents/openai.yaml +2 -0
  170. package/skills/hr-stock-ui-audit/SKILL.md +132 -0
  171. package/skills/hr-stock-ui-audit/agents/openai.yaml +3 -0
  172. package/skills/hr-stock-ui-audit/scripts/scan.mjs +619 -0
  173. package/skills/hr-tdd/LICENSE +21 -0
  174. package/skills/hr-tdd/NOTICE.md +10 -0
  175. package/skills/hr-tdd/SKILL.md +40 -0
  176. package/skills/hr-tdd/agents/openai.yaml +3 -0
  177. package/skills/hr-tdd/mocking.md +39 -0
  178. package/skills/hr-tdd/tests.md +77 -0
  179. package/skills/hr-test-audit/SKILL.md +146 -0
  180. package/skills/hr-test-audit/agents/openai.yaml +3 -0
  181. package/skills/hr-test-audit/scripts/floor-guard.ts +137 -0
  182. package/skills/hr-what-next/SKILL.md +61 -0
  183. package/skills/hr-what-next/agents/openai.yaml +4 -0
  184. package/skills/hr-what-next/references/reporting.md +68 -0
  185. package/skills/hr-writing-for-agents/NOTICE.md +46 -0
  186. package/skills/hr-writing-for-agents/SKILL-MECHANICS.md +83 -0
  187. package/skills/hr-writing-for-agents/SKILL.md +108 -0
  188. package/skills/hr-writing-for-agents/agents/openai.yaml +3 -0
  189. package/skills/hr-writing-pr/NOTICE.md +48 -0
  190. package/skills/hr-writing-pr/SKILL.md +104 -0
  191. package/skills/hr-writing-pr/agents/openai.yaml +2 -0
@@ -0,0 +1,105 @@
1
+ # Variable fonts and OpenType
2
+
3
+ What a font file can do beyond drawing letters and how to reach those abilities from CSS.
4
+
5
+ ## Static vs variable
6
+
7
+ - **Static font:** one weight and one style per file. Regular, medium and bold is three files.
8
+ - **Variable font:** a whole range in one file. Any value in it works, such as `font-weight: 589`.
9
+
10
+ A variable font is not automatically better. At one or two weights, static files can be smaller. At several weights, optical sizes, or custom axes, a variable font usually wins.
11
+
12
+ ## Load intended weights and styles
13
+
14
+ Use a weight or style the active family does not provide and the browser may synthesize it, so load the faces the design uses. `none` disables weight, style, small-cap, superscript and subscript synthesis together and can erase distinctions when the real face is unavailable. Verify the whole fallback stack and every emphasis state before setting it.
15
+
16
+ ```css
17
+ .brand-wordmark {
18
+ /* Safe only after this isolated treatment is verified */
19
+ font-synthesis: none;
20
+ }
21
+ ```
22
+
23
+ For body and interface text, keep synthesis enabled unless a verified font setup supplies every requested form. If only one mode is unwanted, use the specific longhand (`font-synthesis-weight`, `font-synthesis-style` and related properties) instead of the blanket shorthand.
24
+
25
+ ## Axes
26
+
27
+ Variable-font controls, each with a four-letter tag. A font supports only the axes its designer included.
28
+
29
+ | Axis | Tag | Controls |
30
+ | ------------ | ------------------------- | ---------------------------------------------- |
31
+ | Weight | `wght` | Stroke thickness (like `font-weight`) |
32
+ | Optical size | `opsz` | Details and spacing tuned for the display size |
33
+ | Width | `wdth` | Glyph width |
34
+ | Slant | `slnt` | Slant angle |
35
+ | Custom | e.g. `GRAD` (Roboto Flex) | Whatever the designer built |
36
+
37
+ Inter's variable file exposes only `wght` and `opsz`.
38
+
39
+ Optical sizes predate variable fonts, and many families still ship them as separate files. Heldane Text is sturdier and more spaced for reading sizes, Heldane Display finer for large ones.
40
+
41
+ ## Properties over axis tags
42
+
43
+ When a property exists, use it. `font-weight` keeps working when a non-variable fallback renders, where `font-variation-settings` silently does nothing. Save raw tags for custom axes with no property of their own:
44
+
45
+ ```css
46
+ /* Good: common axes use the properties */
47
+ .heading {
48
+ font-weight: 650;
49
+ font-optical-sizing: auto;
50
+ }
51
+
52
+ /* Good: custom axis with no property of its own */
53
+ .heading-grade {
54
+ font-variation-settings: "GRAD" 80;
55
+ }
56
+
57
+ /* Bad: weight via raw tag breaks on fallback fonts */
58
+ .heading {
59
+ font-variation-settings: "wght" 650;
60
+ }
61
+ ```
62
+
63
+ ## OpenType features
64
+
65
+ OpenType is the standard behind almost every modern font. Features are extra built-in options and, unlike axes, work the same on static and variable fonts. A font ships only the features its designer included.
66
+
67
+ | Tag | Feature |
68
+ | ------------- | ----------------------------------------------- |
69
+ | `tnum` | Tabular numbers: every digit the same width |
70
+ | `zero` | Slashed zero: `0` distinct from `O` |
71
+ | `liga` | Ligatures: joins pairs like "fi" into one shape |
72
+ | `ss01`–`ss20` | Stylistic sets (numbered slots) |
73
+ | `cv01`–`cv99` | Character variants (numbered slots) |
74
+
75
+ Same rule as axes. Prefer the `font-variant-*` properties and reserve `font-feature-settings` for tags with no property:
76
+
77
+ ```css
78
+ /* Good: common features use the properties */
79
+ .price {
80
+ font-variant-numeric: tabular-nums;
81
+ }
82
+
83
+ /* Good: slashed zero via the property too */
84
+ .id {
85
+ font-variant-numeric: slashed-zero;
86
+ }
87
+
88
+ /* Good: niche feature with no property of its own */
89
+ .logo {
90
+ font-feature-settings: "ss01" 1;
91
+ }
92
+ ```
93
+
94
+ Tabular numbers matter for changing values. Without them each digit has a different width and the layout shifts as values update.
95
+
96
+ ## Small caps, superscripts, subscripts
97
+
98
+ - **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
99
+ - **Superscripts** sit above the normal line, the 2 in x², and **subscripts** below it, as in H₂O. Enable proper glyphs with `font-variant-position`.
100
+
101
+ Both require the font to include the glyphs.
102
+
103
+ ## Stylistic sets and character variants
104
+
105
+ `ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.
@@ -0,0 +1,57 @@
1
+ # Wrapping and punctuation
2
+
3
+ Where lines start, where they end, where they break and which characters they use.
4
+
5
+ ## Measure (line length)
6
+
7
+ Long lines make it harder for the eye to find the start of the next. For long-form text, aim for 60–75 characters per line.
8
+
9
+ Any unit works. `65ch` measures characters directly, one `ch` being the width of the `0` in the current font, and a pixel or rem cap is just as good. At a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` (`576px`) and `max-w-2xl` (`672px`) both fit. What matters is that a cap exists and the line length sits in range. Recheck it if the body font size changes.
10
+
11
+ ## Alignment
12
+
13
+ `text-align` controls where each line starts and ends. `justify` stretches spaces until both edges line up, which works in specific editorial layouts and nowhere else in an interface.
14
+
15
+ ## Wrapping
16
+
17
+ | Property | Use |
18
+ | --------------------------- | ------------------------------------------------------------------ |
19
+ | `text-wrap: balance` | Distributes text evenly across multiple lines |
20
+ | `text-wrap: pretty` | Avoids leaving a single short word on the final line |
21
+ | `overflow-wrap: break-word` | Lets long words, links and IDs break before escaping the container |
22
+ | `white-space: nowrap` | Keeps labels and badges on one line where a break looks broken |
23
+
24
+ Use `balance` on headings and `pretty` on descriptions. Skip both in long-form text, because browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read.
25
+
26
+ ## Truncation
27
+
28
+ - Single line: `text-overflow: ellipsis`, which needs `overflow: hidden` and `white-space: nowrap`.
29
+ - Multiple lines: `line-clamp` allows any number of lines before the ellipsis.
30
+ - Middle: CSS has no middle ellipsis. Split the string in markup, an end-truncating head and a fixed tail such as the extension or last few characters, or shorten it in script with the full value in `title`. Use it where items differ at the end (`Q3-report…v12-final.pdf`).
31
+ - None: numbers, amounts, dates and anything the user compares get the room they need.
32
+
33
+ Truncation hides content. Where the missing text matters, make the full value available in a tooltip or an expanded view.
34
+
35
+ ## Case
36
+
37
+ `text-transform` changes how case appears without changing the underlying text. Write copy naturally and control presentation with CSS, so a redesign never means rewriting copy.
38
+
39
+ ## Smart punctuation
40
+
41
+ Keyboard characters are not always the best characters:
42
+
43
+ | Instead of | Use |
44
+ | ------------------------ | ---------------------------------------------------------------------- |
45
+ | Straight quotes `"..."` | Curly quotes that curve around the text (keep straight quotes in code) |
46
+ | Hyphen in ranges | En dash: `2010–2020` |
47
+ | Two hyphens for an aside | Em dash character |
48
+ | Three periods `...` | The single ellipsis character `…` |
49
+ | Regular space in `16 px` | ` ` so the value never breaks apart |
50
+ | Uncontrolled word breaks | `­` to mark where a word may break |
51
+
52
+ ## Internationalization
53
+
54
+ Two refinements for mixed-direction text:
55
+
56
+ - **Long paragraphs align by their own language.** A one- or two-line snippet follows the surrounding UI's direction. A paragraph of three or more lines aligns to its own script instead, so an English paragraph stays start-aligned LTR even inside an RTL interface. `text-align: start` with the correct `lang`/`dir` on the paragraph element handles this.
57
+ - **Never reverse digits.** Numbers keep their order in every direction, so a phone number or "541" reads identically in RTL. Browsers handle this through the Unicode bidi algorithm. Never fight it with manual reordering, and wrap mixed number and text values in `<bdi>` where adjacent RTL text disturbs them.
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jakub Krehel
4
+ Copyright (c) 2026 Emil Kowalski
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
@@ -0,0 +1,46 @@
1
+ # Source notices
2
+
3
+ This notice accompanies the hr-better-writing bundle when copied on its own.
4
+
5
+ ## jakubkrehel/skills
6
+
7
+ Source: https://github.com/jakubkrehel/skills (compared at revision `267330e1adfc66a718fb65fa6918c1f06d0a689e`)
8
+
9
+ - `skills/hr-better-accessibility/`, `skills/hr-better-colors/`, `skills/hr-better-layout/`,
10
+ `skills/hr-better-typography/` and `skills/hr-better-writing/`: adapted skill bundles,
11
+ including their supporting references and discovery metadata.
12
+
13
+ Copyright (c) 2026 Jakub Krehel
14
+
15
+ ## emilkowalski/skills
16
+
17
+ Source: https://github.com/emilkowalski/skills (compared at revision `e8a175de22ae1e49370fc144c1f3bb9aeedf988d`)
18
+
19
+ - `skills/hr-better-layout/`, `skills/hr-better-typography/` and `skills/hr-better-writing/`:
20
+ clipping, truncation and plural-form guidance adapted from `skills/break-ui/SKILL.md`.
21
+
22
+ Copyright (c) 2026 Emil Kowalski
23
+
24
+ ## house-rules and MIT permission notice
25
+
26
+ MIT License
27
+
28
+ Copyright (c) 2026 Aaron Queen
29
+
30
+ Permission is hereby granted, free of charge, to any person obtaining a copy
31
+ of this software and associated documentation files (the "Software"), to deal
32
+ in the Software without restriction, including without limitation the rights
33
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
34
+ copies of the Software, and to permit persons to whom the Software is
35
+ furnished to do so, subject to the following conditions:
36
+
37
+ The above copyright notice and this permission notice shall be included in all
38
+ copies or substantial portions of the Software.
39
+
40
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
41
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
42
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
43
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
44
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
45
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
46
+ SOFTWARE.
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: hr-better-writing
3
+ description: "Interface copy rules: button and link labels, error messages, empty states, placeholders, toggles and consistent terminology. Use when writing or reviewing text users see in a web UI; commit messages, PRs, docs and replies belong to hr-plain-prose."
4
+ license: MIT
5
+ metadata:
6
+ upstream: https://github.com/jakubkrehel/skills
7
+ upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
8
+ upstream_path: skills/better-writing/
9
+ local_patches: "Use-when description; name-validation example; plural check at 0, 1 and many (from emilkowalski/skills break-ui)"
10
+ house_rules_patches: "Portable provenance and review verdict"
11
+ break_ui_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/break-ui/SKILL.md
12
+ ---
13
+
14
+ # Interface writing
15
+
16
+ Clear and brief beats clever; consistent beats varied. The best error message is the interaction redesigned so the error cannot happen.
17
+
18
+ How copy renders (capitalization via `text-transform`, truncation, smart punctuation) belongs to `hr-better-typography`. Error markup and announcements (`aria-invalid`, live regions) belong to `hr-better-accessibility`. Room for translated strings belongs to `hr-better-layout`.
19
+
20
+ ## Recon the existing voice
21
+
22
+ Before writing or reviewing, read the copy nearby. Note the product's terminology, its localization conventions and any voice or content style guide.
23
+
24
+ A deliberate brand voice is not a defect. Raise a departure from plain language only when it creates inconsistency, ambiguity, translation risk, or a tone the stakes don't support.
25
+
26
+ ## One voice, flexible tone
27
+
28
+ The product has one voice and its existing copy establishes it. A local edit does not get to invent a new one. Keep terms consistent: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:
29
+
30
+ | Context | Tone |
31
+ | --------------------------------- | ----------------------------- |
32
+ | Success, onboarding, empty states | Warm, can be light |
33
+ | Routine actions, settings | Neutral, minimal |
34
+ | Errors, destructive confirmations | Calm, plain, zero playfulness |
35
+ | Data loss, security | Serious, explicit |
36
+
37
+ ## Address the reader directly
38
+
39
+ In instructional copy, write "you", not "the user". In errors, "we" invites ambiguity and reads as deflection, so prefer "Unable to load content" over "We're having trouble loading this content". In success, onboarding and empty-state copy, an established first-person voice can stay if it reads clearly.
40
+
41
+ Use possessives sparingly: "Favorites" beats "Your Favorites". Hold one perspective throughout a flow.
42
+
43
+ ## Plain words over clever ones
44
+
45
+ Choose words a tired reader gets on the first pass, and delete every word that does no work. No idioms, no colloquialisms, no humor that won't translate.
46
+
47
+ Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible.
48
+
49
+ Never assemble a sentence from fragments around a variable (`"You have " + n + " new messages"`), because word order changes per language. Use a full templated string with proper pluralization: the i18n library's plural forms or `Intl.PluralRules`, checked at 0, 1 and many so "1 members" never ships.
50
+
51
+ ## Verb-first buttons
52
+
53
+ A button label starts with a verb naming the action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or a bare "Yes" and "No" on a consequential action.
54
+
55
+ A confirmation button repeats the consequence, so the dialog is answerable without reading the body. "Delete this project?" offers `Delete project` and `Cancel`.
56
+
57
+ ## Consistent flow vocabulary
58
+
59
+ A multi-step flow uses one vocabulary throughout: "Get started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms makes users wonder whether the buttons do different things.
60
+
61
+ ## Links describe their destination
62
+
63
+ Link text has to make sense out of context, because screen-reader users navigate by a list of the page's links. Write "Read the billing docs". "Click here" fails this and the device-verb rule at once.
64
+
65
+ A bare "Learn more" breaks down as soon as two appear on one page. Suffix each one: "Learn more about exports".
66
+
67
+ ## One capitalization policy
68
+
69
+ Pick title case or sentence case per element type, then apply it to every instance of that type. Sentence case is the safer default. It is calmer, has no per-word rules to remember and localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.
70
+
71
+ ## Settings describe the ON state
72
+
73
+ Label a toggle for what happens when it is on. "Send read receipts" lets users infer the off state; the negative ("Don't send read receipts") turns the toggle into a double negative.
74
+
75
+ Link straight to a referenced setting rather than describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".
76
+
77
+ ## Errors say how to fix, next to where it broke
78
+
79
+ An error is an instruction, and it belongs beside the field that failed:
80
+
81
+ | Bad | Good |
82
+ | --------------------------- | ---------------------------------------------------- |
83
+ | That password is too short | Choose a password with at least 8 characters |
84
+ | Invalid date | Enter a date as DD/MM/YYYY |
85
+ | Oops! Something went wrong. | Unable to save. Check your connection and try again. |
86
+
87
+ No blame, no "oops", no exclamation marks. Phrase hints positively ("Use digits only", not "Don't use letters or symbols") and show them before the mistake, not after. When the same error keeps firing, redesign the interaction instead of rewording it.
88
+
89
+ ## Empty states point forward
90
+
91
+ An empty state says what this place is, how to fill it and offers one clear next action:
92
+
93
+ ```html
94
+ <!-- Bad: a shrug -->
95
+ <p>No results.</p>
96
+
97
+ <!-- Good: orientation plus a next step -->
98
+ <p class="font-medium">No projects yet</p>
99
+ <p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
100
+ <button class="mt-4">Create a project</button>
101
+ ```
102
+
103
+ A search or filter empty state names the query and offers an exit: "No results for 'quarterly'. Clear filters". Never park persistent information in an empty state. It disappears the moment content exists.
104
+
105
+ ## Placeholders are examples, not labels
106
+
107
+ A placeholder shows the expected format: `name@example.com`, `DD/MM/YYYY`. It vanishes on input, so it is never the only label. Every field keeps a visible one.
108
+
109
+ ## Reporting
110
+
111
+ **Severity.** `HIGH` misleads the user or hides how to recover from an error. `MEDIUM` breaks voice, terminology, or capitalization consistency. `LOW` is isolated wording polish.
112
+
113
+ **Verification.** Source alone is enough here. Check every label against the action it invokes, every error for a stated fix and terminology against the copy around it. No browser check is required.
114
+
115
+ **Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
116
+
117
+ | Severity | Location | Before | After | Why |
118
+ | -------- | -------- | ------ | ----- | --- |
119
+
120
+ `Location` is `path/to/file:line`. `Why` names the principle and the user impact.
121
+
122
+ Report `Block` when any `HIGH` remains. With partial coverage and no `HIGH`, report the coverage gap without a verdict. With complete coverage and no `HIGH`, report `Approve`, leaving lower-severity findings in the table as work to do. With nothing to report, state "No actionable writing findings" and report verification.
@@ -0,0 +1,3 @@
1
+ interface:
2
+ display_name: "HR: Better Writing"
3
+ short_description: "UX writing, interface copy and microcopy"
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: hr-change-impact
3
+ description: "Check what a change can break beyond the lines it edits, and back the claim that it is safe with something that ran. Use when the user asks what a change might break, wants its impact checked before merging, or distrusts a small diff."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Change impact
8
+
9
+ The diff shows what changed. This skill asks what else depends on the old
10
+ behavior, and whether the change is safe for a reason someone has seen work.
11
+ Follow project guidance for commands, test runners and domain safeguards.
12
+
13
+ ## Scope the change
14
+
15
+ Read the whole diff and the code around each hunk. Write one or two sentences
16
+ on what the change does, including behavior a reader of the diff could miss:
17
+ a new default, a reordered side effect, a changed error type, a value that is
18
+ now computed lazily or cached. If you cannot explain the change yet, read the
19
+ code first (see `hr-explain-code`) before judging its impact.
20
+
21
+ When the reason for old behavior affects the risk, inspect relevant history.
22
+ Use a scoped `git log -p` or `git log -S<symbol>` where it can answer that
23
+ question; a literal symbol search may miss renames or indirect behavior.
24
+
25
+ ## Look past the call sites
26
+
27
+ List direct callers quickly; a compiler or a symbol search usually covers them,
28
+ and they are rarely where the surprise is. Spend the effort on coupling that a
29
+ symbol search does not see:
30
+
31
+ - **Stored and serialized shapes.** Field names, enum values, JSON keys,
32
+ cache keys, database columns, file formats and anything written today and
33
+ read back after a deploy or by an older version.
34
+ - **Other readers.** Another process, service, job, script or client that
35
+ consumes the output, the queue message, the log line or the API response.
36
+ Search for the literal strings, not only the symbol.
37
+ - **Supported surfaces.** Other screens, entry points, clients, providers and
38
+ connection modes that reach the behavior. Check reverse operations and
39
+ state transitions too, such as enabling/disabling or connecting/disconnecting,
40
+ when the feature supports them. Use the project's actual supported cases;
41
+ do not invent surfaces or expand project-mandated verification to cover
42
+ unsupported cases. Keep the focused probe below when existing tests do not
43
+ exercise a load-bearing assumption.
44
+ - **Timing.** Startup order, background workers, scheduled jobs, retries,
45
+ timeouts and shutdown. A change that is correct on the request path can
46
+ break a job that runs once a night.
47
+ - **Configuration.** Environment variables, feature flags, defaults that
48
+ differ between environments, and code paths only one flag value reaches.
49
+ - **Dependencies as pinned.** How the library behaves at the version in the
50
+ lockfile, including local patches the project applies, not the version in
51
+ current upstream docs. Check the effective installed source, patch files or
52
+ changelog when the change relies on a specific behavior.
53
+
54
+ Each search is a finding. "No other reader of `order_status` found in this
55
+ repository or its deploy config" is worth reporting; say where you looked.
56
+ Never name a caller, consumer or API you have not seen at a real location.
57
+
58
+ ## Find the load-bearing assumption
59
+
60
+ A change that looks risky usually rests on one or two facts: no
61
+ consumer reads the old field, the flag is off in production, the migration
62
+ runs before the new code. Name those assumptions explicitly. Then put most of
63
+ the remaining effort into confirming or breaking them, rather than adding more
64
+ hypothetical risks to a list.
65
+
66
+ A risk that depends on an assumption you have already confirmed does not need
67
+ its own entry. A risk nobody can check deserves a sentence on why it cannot be
68
+ checked and who could.
69
+
70
+ ## Back each claim
71
+
72
+ A claim can rest on your word alone, on a source location that shows it, on
73
+ a failure path you walked step by step, or on real code that ran and gave the
74
+ result. These are not equal, and the reader cannot tell them apart unless you
75
+ say. Next to each important claim, state in a few words what backs it: "the
76
+ only reader is `billing/export.py:88`", "traced: a missing key falls through
77
+ to the default", "ran `test_legacy_payload`, passes".
78
+
79
+ When feasible within the selected scope, reproduce the behavior in the
80
+ running application for the strongest backing. Get the load-bearing assumption
81
+ at least to something that ran. A careful trace is enough for lesser claims.
82
+ A claim with nothing behind it is a gap; report it as one instead of dressing it up.
83
+
84
+ Prefer evidence that already exists: run the tests that cover the changed code
85
+ and read what they actually assert. When none exercise the assumption, write
86
+ the smallest probe that does, such as a script that round-trips an old
87
+ serialized record through the new code. Keep probes outside committed source,
88
+ or delete them before reporting, and say in the report that you did.
89
+
90
+ ## Report
91
+
92
+ Use these parts, in order:
93
+
94
+ 1. **What it does**: the change in plain terms, with the non-obvious behavior.
95
+ 2. **What it relies on**: each load-bearing assumption, its support, and
96
+ whether it held.
97
+ 3. **Risks**: for each real one, the location, how likely it is, what it costs
98
+ if it happens, and how to check it.
99
+ 4. **Ruled out**: concerns you examined and dismissed, with where you looked.
100
+ This keeps a reviewer from redoing the same search.
101
+ 5. **Before merging**: the specific check to run, with the command when there
102
+ is one, or "none needed" with the reason.
103
+
104
+ Keep the list of risks short. Three real ones with locations beat fifteen
105
+ possibilities. Before sharing publicly, follow the project's data-classification
106
+ policy. Remove credentials, personal data, private project names and URLs,
107
+ and local paths.
108
+
109
+ ## Related skills
110
+
111
+ - `hr-explain-code` when you need to understand the code before judging a change.
112
+ - `hr-code-review` for standards, style and spec conformance of the same diff.
113
+ - `hr-diagnosing-bugs` once something is actually broken.
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "HR: Change impact"
3
+ short_description: "Check what a change could break before merging"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aaron Queen
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,26 @@
1
+ # Source notices
2
+
3
+ Source: https://github.com/no-human-ai/no_human (compared at revision `9b50bf6`)
4
+
5
+ The evidence method's test-weakening assessment and refutation of completion
6
+ claims are informed by this source. The method is independently written.
7
+
8
+ Copyright (c) 2026 Eyal Golan
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.