@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.
- package/CONTRIBUTING.md +54 -0
- package/LICENSE +21 -0
- package/README.md +347 -2
- package/THIRD_PARTY_NOTICES.md +188 -0
- package/compose.mjs +119 -0
- package/composition.mjs +353 -0
- package/config-view.mjs +194 -0
- package/config.mjs +320 -0
- package/docs/assets/banner-dark.png +0 -0
- package/docs/assets/banner-light.png +0 -0
- package/docs/assets/overview.png +0 -0
- package/docs/configuration.md +193 -0
- package/docs/npm-release.md +45 -0
- package/docs/skill-names.md +50 -0
- package/examples/person/house-rules.json +15 -0
- package/examples/person/rules/10-tooling.md +8 -0
- package/examples/person/rules/20-reporting.md +9 -0
- package/examples/project/AGENTS.md +18 -0
- package/package.json +40 -4
- package/rule-references.mjs +91 -0
- package/rules/core.md +431 -0
- package/rules/modifiers/coded-offers.md +40 -0
- package/rules/modifiers/effort-estimates.md +41 -0
- package/rules/modifiers/land-when-done.md +12 -0
- package/rules/modifiers/low-quota-handoff.md +19 -0
- package/rules/modifiers/multi-agent.md +34 -0
- package/rules/modifiers/no-attribution.md +10 -0
- package/rules/modifiers/plan-files.md +50 -0
- package/rules/modifiers/question-cards.md +48 -0
- package/rules/modifiers/release-batching.md +13 -0
- package/rules/modifiers/scratch-on-disk.md +15 -0
- package/rules/modifiers/shared-host-load.md +48 -0
- package/rules/modifiers/solo-operator.md +13 -0
- package/rules/modifiers/squash-landing.md +22 -0
- package/rules/modifiers/swarmail.md +12 -0
- package/rules/references/github-actions.md +45 -0
- package/rules/references/landing.md +39 -0
- package/rules/references/multi-agent.md +47 -0
- package/rules/references/release-batching.md +43 -0
- package/rules/references/squash-landing.md +44 -0
- package/setup.mjs +375 -0
- package/skills/hr-agent-guidance-audit/LICENSE +21 -0
- package/skills/hr-agent-guidance-audit/SKILL.md +86 -0
- package/skills/hr-agent-guidance-audit/agents/openai.yaml +2 -0
- package/skills/hr-agent-guidance-audit/references/records-and-lessons.md +60 -0
- package/skills/hr-agent-guidance-refresh/LICENSE +21 -0
- package/skills/hr-agent-guidance-refresh/SKILL.md +68 -0
- package/skills/hr-agent-guidance-refresh/agents/openai.yaml +2 -0
- package/skills/hr-agent-guidance-refresh/references/verification.md +47 -0
- package/skills/hr-api-exposure-check/SKILL.md +159 -0
- package/skills/hr-api-exposure-check/agents/openai.yaml +3 -0
- package/skills/hr-audit-choices/SKILL.md +67 -0
- package/skills/hr-audit-choices/agents/openai.yaml +2 -0
- package/skills/hr-benchmarking/NOTICE.md +36 -0
- package/skills/hr-benchmarking/SKILL.md +316 -0
- package/skills/hr-benchmarking/agents/openai.yaml +2 -0
- package/skills/hr-benchmarking/references/javascript.md +17 -0
- package/skills/hr-benchmarking/references/priority-findings-20261006.md +115 -0
- package/skills/hr-benchmarking/references/tools.md +160 -0
- package/skills/hr-benchmarking/scripts/process-attribution.ps1 +20 -0
- package/skills/hr-benchmarking/scripts/process-attribution.py +107 -0
- package/skills/hr-better-accessibility/LICENSE +22 -0
- package/skills/hr-better-accessibility/NOTICE.md +46 -0
- package/skills/hr-better-accessibility/SKILL.md +119 -0
- package/skills/hr-better-accessibility/agents/openai.yaml +3 -0
- package/skills/hr-better-accessibility/focus-and-keyboard.md +130 -0
- package/skills/hr-better-accessibility/forms.md +82 -0
- package/skills/hr-better-accessibility/hit-areas.md +98 -0
- package/skills/hr-better-accessibility/motion-and-zoom.md +81 -0
- package/skills/hr-better-accessibility/screen-readers.md +101 -0
- package/skills/hr-better-accessibility/semantics-and-aria.md +84 -0
- package/skills/hr-better-colors/LICENSE +21 -0
- package/skills/hr-better-colors/NOTICE.md +37 -0
- package/skills/hr-better-colors/SKILL.md +114 -0
- package/skills/hr-better-colors/agents/openai.yaml +3 -0
- package/skills/hr-better-colors/color-formats.md +90 -0
- package/skills/hr-better-colors/color-usage.md +140 -0
- package/skills/hr-better-colors/contrast.md +80 -0
- package/skills/hr-better-colors/palette-generation.md +104 -0
- package/skills/hr-better-colors/palette-structure.md +76 -0
- package/skills/hr-better-colors/token-naming.md +97 -0
- package/skills/hr-better-layout/LICENSE +22 -0
- package/skills/hr-better-layout/NOTICE.md +48 -0
- package/skills/hr-better-layout/SKILL.md +92 -0
- package/skills/hr-better-layout/agents/openai.yaml +3 -0
- package/skills/hr-better-layout/grouping-and-alignment.md +144 -0
- package/skills/hr-better-layout/spacing-and-adaptivity.md +215 -0
- package/skills/hr-better-typography/LICENSE +22 -0
- package/skills/hr-better-typography/NOTICE.md +46 -0
- package/skills/hr-better-typography/SKILL.md +172 -0
- package/skills/hr-better-typography/agents/openai.yaml +3 -0
- package/skills/hr-better-typography/choosing-fonts.md +69 -0
- package/skills/hr-better-typography/css-cheat-sheet.md +65 -0
- package/skills/hr-better-typography/details-and-accessibility.md +119 -0
- package/skills/hr-better-typography/spacing-and-sizing.md +131 -0
- package/skills/hr-better-typography/variable-fonts-and-opentype.md +105 -0
- package/skills/hr-better-typography/wrapping-and-punctuation.md +57 -0
- package/skills/hr-better-writing/LICENSE +22 -0
- package/skills/hr-better-writing/NOTICE.md +46 -0
- package/skills/hr-better-writing/SKILL.md +122 -0
- package/skills/hr-better-writing/agents/openai.yaml +3 -0
- package/skills/hr-change-impact/SKILL.md +113 -0
- package/skills/hr-change-impact/agents/openai.yaml +5 -0
- package/skills/hr-code-review/LICENSE +21 -0
- package/skills/hr-code-review/NOTICE.md +26 -0
- package/skills/hr-code-review/SKILL.md +147 -0
- package/skills/hr-code-review/agents/openai.yaml +3 -0
- package/skills/hr-code-review/references/evidence.md +57 -0
- package/skills/hr-design-exploration/SKILL.md +82 -0
- package/skills/hr-design-exploration/agents/openai.yaml +4 -0
- package/skills/hr-diagnosing-bugs/NOTICE.md +45 -0
- package/skills/hr-diagnosing-bugs/SKILL.md +108 -0
- package/skills/hr-diagnosing-bugs/agents/openai.yaml +3 -0
- package/skills/hr-diagnosing-bugs/references/reporting.md +72 -0
- package/skills/hr-explain-code/NOTICE.md +37 -0
- package/skills/hr-explain-code/SKILL.md +110 -0
- package/skills/hr-explain-code/agents/openai.yaml +5 -0
- package/skills/hr-explain-code/references/helper-brief.md +39 -0
- package/skills/hr-extract-shared-steps/SKILL.md +134 -0
- package/skills/hr-extract-shared-steps/agents/openai.yaml +3 -0
- package/skills/hr-handoff/SKILL.md +91 -0
- package/skills/hr-handoff/agents/openai.yaml +5 -0
- package/skills/hr-handoff/assets/ledger.example.json +10 -0
- package/skills/hr-handoff/assets/receipt.example.json +76 -0
- package/skills/hr-handoff/assets/source.example.json +20 -0
- package/skills/hr-handoff/references/reconciliation.md +105 -0
- package/skills/hr-handoff/scripts/check-reconciliation.mjs +282 -0
- package/skills/hr-house-rules-setup/SKILL.md +100 -0
- package/skills/hr-house-rules-setup/agents/openai.yaml +5 -0
- package/skills/hr-issue-tracker-setup/SKILL.md +49 -0
- package/skills/hr-issue-tracker-setup/agents/openai.yaml +5 -0
- package/skills/hr-lean-plan/SKILL.md +142 -0
- package/skills/hr-lean-plan/agents/openai.yaml +5 -0
- package/skills/hr-maintainability-review/SKILL.md +176 -0
- package/skills/hr-maintainability-review/agents/openai.yaml +5 -0
- package/skills/hr-manual-qa/NOTICE.md +36 -0
- package/skills/hr-manual-qa/SKILL.md +37 -0
- package/skills/hr-manual-qa/agents/openai.yaml +3 -0
- package/skills/hr-navigation-retro/LICENSE +21 -0
- package/skills/hr-navigation-retro/NOTICE.md +5 -0
- package/skills/hr-navigation-retro/SKILL.md +86 -0
- package/skills/hr-navigation-retro/agents/openai.yaml +4 -0
- package/skills/hr-navigation-retro/references/inputs.md +67 -0
- package/skills/hr-navigation-retro/scripts/retro.py +552 -0
- package/skills/hr-navigation-retro/scripts/transcripts.py +205 -0
- package/skills/hr-ordering-tests/SKILL.md +51 -0
- package/skills/hr-ordering-tests/agents/openai.yaml +2 -0
- package/skills/hr-plain-prose/SKILL.md +261 -0
- package/skills/hr-plain-prose/agents/openai.yaml +3 -0
- package/skills/hr-plain-prose/scripts/check.mjs +331 -0
- package/skills/hr-pr-followup/LICENSE +21 -0
- package/skills/hr-pr-followup/NOTICE.md +9 -0
- package/skills/hr-pr-followup/SKILL.md +71 -0
- package/skills/hr-pr-followup/agents/openai.yaml +2 -0
- package/skills/hr-pr-followup/references/review-helpers.md +90 -0
- package/skills/hr-pr-followup/scripts/check-pr-review.ts +510 -0
- package/skills/hr-pr-followup/scripts/resolve-pr-thread.ts +219 -0
- package/skills/hr-progress-report/SKILL.md +49 -0
- package/skills/hr-progress-report/agents/openai.yaml +5 -0
- package/skills/hr-read-reddit/SKILL.md +44 -0
- package/skills/hr-read-reddit/agents/openai.yaml +2 -0
- package/skills/hr-read-reddit/scripts/reddit.ts +252 -0
- package/skills/hr-read-x-links/SKILL.md +42 -0
- package/skills/hr-read-x-links/agents/openai.yaml +2 -0
- package/skills/hr-read-x-links/scripts/x-post.ts +264 -0
- package/skills/hr-split-to-prs/LICENSE +21 -0
- package/skills/hr-split-to-prs/NOTICE.md +9 -0
- package/skills/hr-split-to-prs/SKILL.md +61 -0
- package/skills/hr-split-to-prs/agents/openai.yaml +2 -0
- package/skills/hr-stock-ui-audit/SKILL.md +132 -0
- package/skills/hr-stock-ui-audit/agents/openai.yaml +3 -0
- package/skills/hr-stock-ui-audit/scripts/scan.mjs +619 -0
- package/skills/hr-tdd/LICENSE +21 -0
- package/skills/hr-tdd/NOTICE.md +10 -0
- package/skills/hr-tdd/SKILL.md +40 -0
- package/skills/hr-tdd/agents/openai.yaml +3 -0
- package/skills/hr-tdd/mocking.md +39 -0
- package/skills/hr-tdd/tests.md +77 -0
- package/skills/hr-test-audit/SKILL.md +146 -0
- package/skills/hr-test-audit/agents/openai.yaml +3 -0
- package/skills/hr-test-audit/scripts/floor-guard.ts +137 -0
- package/skills/hr-what-next/SKILL.md +61 -0
- package/skills/hr-what-next/agents/openai.yaml +4 -0
- package/skills/hr-what-next/references/reporting.md +68 -0
- package/skills/hr-writing-for-agents/NOTICE.md +46 -0
- package/skills/hr-writing-for-agents/SKILL-MECHANICS.md +83 -0
- package/skills/hr-writing-for-agents/SKILL.md +108 -0
- package/skills/hr-writing-for-agents/agents/openai.yaml +3 -0
- package/skills/hr-writing-pr/NOTICE.md +48 -0
- package/skills/hr-writing-pr/SKILL.md +104 -0
- 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,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,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.
|