swe-workflow-skills 0.1.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 (177) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +144 -0
  3. package/VERSION +1 -0
  4. package/bin/cli.mjs +44 -0
  5. package/catalog.json +225 -0
  6. package/commands/role.md +34 -0
  7. package/hooks/session-start.mjs +118 -0
  8. package/install.mjs +318 -0
  9. package/package.json +47 -0
  10. package/roles.json +194 -0
  11. package/scripts/resolve.mjs +296 -0
  12. package/skills/accessibility-design/SKILL.md +128 -0
  13. package/skills/accessibility-design/evals/evals.json +51 -0
  14. package/skills/accessibility-design/references/accessibility-patterns.md +321 -0
  15. package/skills/api-design/SKILL.md +144 -0
  16. package/skills/api-design/evals/evals.json +48 -0
  17. package/skills/api-design/references/rest-conventions.md +147 -0
  18. package/skills/api-design/templates/api-spec.md +156 -0
  19. package/skills/architecture-design/SKILL.md +86 -0
  20. package/skills/architecture-design/evals/evals.json +44 -0
  21. package/skills/architecture-design/references/clean-architecture.md +147 -0
  22. package/skills/architecture-design/references/component-principles.md +129 -0
  23. package/skills/architecture-design/references/principles.md +81 -0
  24. package/skills/architecture-design/references/solid-principles.md +106 -0
  25. package/skills/architecture-design/templates/adr.md +63 -0
  26. package/skills/architecture-documentation/SKILL.md +126 -0
  27. package/skills/architecture-documentation/evals/evals.json +44 -0
  28. package/skills/architecture-documentation/references/abstraction-levels.md +91 -0
  29. package/skills/architecture-documentation/references/diagram-tooling.md +141 -0
  30. package/skills/architecture-documentation/templates/architecture-doc.md +171 -0
  31. package/skills/bug-investigating/SKILL.md +133 -0
  32. package/skills/bug-investigating/evals/evals.json +56 -0
  33. package/skills/bug-investigating/references/common-bugs.md +62 -0
  34. package/skills/bug-investigating/references/debugging-patterns.md +94 -0
  35. package/skills/cicd-pipeline/SKILL.md +87 -0
  36. package/skills/cicd-pipeline/evals/evals.json +34 -0
  37. package/skills/cicd-pipeline/references/pipeline-patterns.md +206 -0
  38. package/skills/cicd-pipeline/templates/github-actions.md +206 -0
  39. package/skills/code-reviewing/SKILL.md +92 -0
  40. package/skills/code-reviewing/evals/evals.json +62 -0
  41. package/skills/code-reviewing/references/error-handling.md +108 -0
  42. package/skills/code-reviewing/references/review-checklist.md +144 -0
  43. package/skills/configuration-strategy/SKILL.md +109 -0
  44. package/skills/configuration-strategy/evals/evals.json +41 -0
  45. package/skills/configuration-strategy/references/config-patterns.md +161 -0
  46. package/skills/containerization/SKILL.md +90 -0
  47. package/skills/containerization/evals/evals.json +36 -0
  48. package/skills/containerization/references/dockerfile-patterns.md +168 -0
  49. package/skills/containerization/templates/dockerfile.md +154 -0
  50. package/skills/data-modeling/SKILL.md +83 -0
  51. package/skills/data-modeling/evals/evals.json +43 -0
  52. package/skills/data-modeling/references/conventions.md +57 -0
  53. package/skills/data-modeling/templates/schema.md +120 -0
  54. package/skills/dependency-impact-analysis/SKILL.md +113 -0
  55. package/skills/dependency-impact-analysis/evals/evals.json +41 -0
  56. package/skills/dependency-impact-analysis/references/impact-patterns.md +150 -0
  57. package/skills/dependency-management/SKILL.md +161 -0
  58. package/skills/dependency-management/evals/evals.json +48 -0
  59. package/skills/dependency-management/references/evaluation-checklist.md +127 -0
  60. package/skills/deployment-checklist/SKILL.md +132 -0
  61. package/skills/deployment-checklist/evals/evals.json +58 -0
  62. package/skills/deployment-checklist/references/pre-deploy-gates.md +91 -0
  63. package/skills/deployment-repo/SKILL.md +190 -0
  64. package/skills/deployment-repo/evals/evals.json +44 -0
  65. package/skills/deployment-repo/references/deployment-repo-patterns.md +258 -0
  66. package/skills/deployment-repo/references/version-compatibility.md +227 -0
  67. package/skills/deployment-repo/templates/deployment-repo-structure.md +226 -0
  68. package/skills/effort-estimation/SKILL.md +95 -0
  69. package/skills/effort-estimation/evals/evals.json +32 -0
  70. package/skills/effort-estimation/references/estimation-methods.md +154 -0
  71. package/skills/feature-planning/SKILL.md +84 -0
  72. package/skills/feature-planning/evals/evals.json +44 -0
  73. package/skills/feature-planning/templates/plan.md +55 -0
  74. package/skills/feature-planning/templates/task.md +26 -0
  75. package/skills/frontend-architecture/SKILL.md +154 -0
  76. package/skills/frontend-architecture/evals/evals.json +34 -0
  77. package/skills/frontend-architecture/references/component-patterns.md +264 -0
  78. package/skills/frontend-architecture/templates/folder-structure.md +203 -0
  79. package/skills/git-workflow/SKILL.md +127 -0
  80. package/skills/git-workflow/evals/evals.json +44 -0
  81. package/skills/git-workflow/references/conventions.md +142 -0
  82. package/skills/git-workflow/templates/pull-request.md +57 -0
  83. package/skills/gitops-delivery/SKILL.md +319 -0
  84. package/skills/gitops-delivery/evals/evals.json +44 -0
  85. package/skills/gitops-delivery/references/gitops-patterns.md +478 -0
  86. package/skills/gitops-delivery/templates/gitops-config.md +196 -0
  87. package/skills/incident-response/SKILL.md +130 -0
  88. package/skills/incident-response/evals/evals.json +55 -0
  89. package/skills/incident-response/references/communication-templates.md +134 -0
  90. package/skills/incident-response/references/severity-levels.md +77 -0
  91. package/skills/incident-response/templates/incident-timeline.md +57 -0
  92. package/skills/infrastructure-as-code/SKILL.md +86 -0
  93. package/skills/infrastructure-as-code/evals/evals.json +33 -0
  94. package/skills/infrastructure-as-code/references/iac-patterns.md +179 -0
  95. package/skills/infrastructure-as-code/templates/terraform-module.md +158 -0
  96. package/skills/metrics-and-okrs/SKILL.md +113 -0
  97. package/skills/metrics-and-okrs/evals/evals.json +33 -0
  98. package/skills/metrics-and-okrs/references/metric-catalog.md +90 -0
  99. package/skills/metrics-and-okrs/templates/okr-document.md +61 -0
  100. package/skills/ml-experiment-tracking/SKILL.md +96 -0
  101. package/skills/ml-experiment-tracking/evals/evals.json +32 -0
  102. package/skills/ml-experiment-tracking/references/tracking-tools.md +127 -0
  103. package/skills/ml-model-deployment/SKILL.md +106 -0
  104. package/skills/ml-model-deployment/evals/evals.json +34 -0
  105. package/skills/ml-model-deployment/references/serving-patterns.md +162 -0
  106. package/skills/ml-pipeline-design/SKILL.md +162 -0
  107. package/skills/ml-pipeline-design/evals/evals.json +34 -0
  108. package/skills/ml-pipeline-design/references/pipeline-components.md +174 -0
  109. package/skills/observability-design/SKILL.md +162 -0
  110. package/skills/observability-design/evals/evals.json +52 -0
  111. package/skills/observability-design/references/logging-patterns.md +229 -0
  112. package/skills/observability-design/references/slo-framework.md +151 -0
  113. package/skills/observability-design/templates/slo-document.md +80 -0
  114. package/skills/performance-optimization/SKILL.md +83 -0
  115. package/skills/performance-optimization/evals/evals.json +47 -0
  116. package/skills/performance-optimization/references/bottleneck-patterns.md +256 -0
  117. package/skills/performance-optimization/references/concurrency.md +101 -0
  118. package/skills/prd-writing/SKILL.md +109 -0
  119. package/skills/prd-writing/evals/evals.json +33 -0
  120. package/skills/prd-writing/references/prd-examples.md +132 -0
  121. package/skills/prd-writing/templates/prd.md +71 -0
  122. package/skills/prd-writing/templates/rfc.md +79 -0
  123. package/skills/project-documentation/SKILL.md +104 -0
  124. package/skills/project-documentation/evals/evals.json +48 -0
  125. package/skills/project-documentation/references/contributing-guide.md +100 -0
  126. package/skills/project-documentation/templates/changelog.md +59 -0
  127. package/skills/project-documentation/templates/readme.md +121 -0
  128. package/skills/project-proposal/SKILL.md +90 -0
  129. package/skills/project-proposal/evals/evals.json +31 -0
  130. package/skills/project-proposal/references/proposal-examples.md +140 -0
  131. package/skills/project-proposal/templates/proposal.md +76 -0
  132. package/skills/project-review/SKILL.md +111 -0
  133. package/skills/project-review/evals/evals.json +42 -0
  134. package/skills/refactoring/SKILL.md +90 -0
  135. package/skills/refactoring/evals/evals.json +44 -0
  136. package/skills/refactoring/references/transformations.md +132 -0
  137. package/skills/retrospective/SKILL.md +157 -0
  138. package/skills/retrospective/evals/evals.json +34 -0
  139. package/skills/retrospective/references/facilitation-guide.md +130 -0
  140. package/skills/retrospective/templates/post-mortem.md +121 -0
  141. package/skills/rollback-strategy/SKILL.md +116 -0
  142. package/skills/rollback-strategy/evals/evals.json +55 -0
  143. package/skills/rollback-strategy/references/rollback-patterns.md +125 -0
  144. package/skills/rollback-strategy/templates/rollback-plan.md +69 -0
  145. package/skills/security-audit/SKILL.md +146 -0
  146. package/skills/security-audit/evals/evals.json +66 -0
  147. package/skills/security-audit/references/owasp-top-10.md +167 -0
  148. package/skills/security-audit/templates/security-report.md +79 -0
  149. package/skills/skill-router/SKILL.md +171 -0
  150. package/skills/skill-router/evals/evals.json +39 -0
  151. package/skills/strategic-review/SKILL.md +106 -0
  152. package/skills/strategic-review/evals/evals.json +42 -0
  153. package/skills/strategic-review/templates/full-review-prompt.md +84 -0
  154. package/skills/tdd-workflow/SKILL.md +147 -0
  155. package/skills/tdd-workflow/evals/evals.json +58 -0
  156. package/skills/tdd-workflow/references/test-quality.md +71 -0
  157. package/skills/technical-debt-review/SKILL.md +113 -0
  158. package/skills/technical-debt-review/evals/evals.json +41 -0
  159. package/skills/technical-debt-review/references/debt-taxonomy.md +124 -0
  160. package/skills/technical-debt-review/templates/debt-audit.md +85 -0
  161. package/skills/test-data-strategy/SKILL.md +129 -0
  162. package/skills/test-data-strategy/evals/evals.json +49 -0
  163. package/skills/test-data-strategy/references/data-generation-patterns.md +341 -0
  164. package/skills/test-suite-design/SKILL.md +137 -0
  165. package/skills/test-suite-design/evals/evals.json +69 -0
  166. package/skills/test-suite-design/references/test-infrastructure.md +175 -0
  167. package/skills/test-suite-design/references/testing-pyramid.md +140 -0
  168. package/skills/ui-ux-design/SKILL.md +117 -0
  169. package/skills/ui-ux-design/evals/evals.json +35 -0
  170. package/skills/ui-ux-design/references/interaction-patterns.md +145 -0
  171. package/skills/ui-ux-design/templates/screen-spec.md +97 -0
  172. package/skills/verification-before-completion/SKILL.md +85 -0
  173. package/skills/verification-before-completion/evals/evals.json +53 -0
  174. package/skills/writing-skills/SKILL.md +87 -0
  175. package/skills/writing-skills/evals/evals.json +41 -0
  176. package/skills/writing-skills/references/pressure-testing.md +69 -0
  177. package/uninstall.mjs +182 -0
@@ -0,0 +1,145 @@
1
+ # Interaction Patterns
2
+
3
+ ## Contents
4
+ - Loading patterns
5
+ - Error handling patterns
6
+ - Form patterns
7
+ - Navigation patterns
8
+ - Feedback patterns
9
+ - Mobile-specific patterns
10
+
11
+ ## Loading Patterns
12
+
13
+ ### Skeleton screens (recommended default)
14
+ Show the layout shape with placeholder content while data loads. Feels faster than a spinner because the user sees the page structure immediately.
15
+
16
+ Use for: Page loads, list views, cards, profiles — any content with a predictable layout.
17
+ Avoid for: Actions with unpredictable duration (file uploads, complex processing).
18
+
19
+ ### Spinner / Progress indicator
20
+ Use a spinner for short waits (< 3 seconds) when the layout isn't predictable. Use a progress bar for longer operations where progress can be measured (file upload, data import).
21
+
22
+ Rules:
23
+ - Don't show a spinner for operations under 200ms — it creates visual noise
24
+ - After 1 second, add a text label ("Loading your dashboard...")
25
+ - After 10 seconds, add a "taking longer than usual" message with an option to cancel or retry
26
+ - Never show a spinner without an eventual timeout or escape
27
+
28
+ ### Optimistic updates
29
+ Show the result of an action immediately, before the server confirms it. Roll back if the server rejects it.
30
+
31
+ Use for: Likes, toggles, form edits, adding items to lists — any fast, low-risk action.
32
+ Avoid for: Payments, deletions, actions with side effects that can't be reversed.
33
+
34
+ ### Stale-while-revalidate
35
+ Show cached data immediately, fetch fresh data in the background, then update seamlessly. The user never sees a loading state for data they've seen before.
36
+
37
+ Use for: Dashboards, lists, profiles — any screen the user visits repeatedly.
38
+
39
+ ## Error Handling Patterns
40
+
41
+ ### Inline field errors (forms)
42
+ Show the error next to the field that caused it, in red with an icon. Don't clear the user's input.
43
+
44
+ ```
45
+ Email: [john@example]
46
+ ⚠ Please enter a valid email address
47
+ ```
48
+
49
+ ### Error banner (page-level)
50
+ Show a dismissible banner at the top of the page for non-field-specific errors (network failure, server error, permission denied).
51
+
52
+ ### Error page (full-page)
53
+ Use for unrecoverable errors: 404, 500, maintenance mode. Include: what happened (without technical jargon), what the user can do (go back, try again, contact support).
54
+
55
+ ### Retry pattern
56
+ For transient errors (network timeout, server 503), offer automatic retry with exponential backoff, plus a manual "Try Again" button. Show what happened: "Couldn't load your data. Retrying..." then "Still having trouble. [Try Again]"
57
+
58
+ ### Graceful degradation
59
+ When a non-critical component fails, don't break the whole page. Show a localized error: "Recommendations unavailable" instead of a full error page, while the rest of the page works normally.
60
+
61
+ ## Form Patterns
62
+
63
+ ### Validation timing
64
+
65
+ | Strategy | When to validate | Best for |
66
+ |----------|-----------------|----------|
67
+ | On blur | When user leaves a field | Most forms — validates without being intrusive |
68
+ | On submit | When user submits | Simple forms with few fields |
69
+ | Real-time | As user types (debounced) | Username availability, password strength |
70
+ | On change | After first submission attempt | Re-validation after an error was shown |
71
+
72
+ Recommended combo: Validate on submit first, then switch to on-blur/on-change for fields that had errors (so the user sees errors clear as they fix them).
73
+
74
+ ### Multi-step forms
75
+
76
+ - Show a progress indicator (step 1 of 4, or a progress bar)
77
+ - Save data on each step (don't lose progress on navigation)
78
+ - Allow backward navigation without losing data
79
+ - Show a summary/review step before final submission
80
+ - Each step should have a clear purpose and title
81
+
82
+ ### Inline editing
83
+
84
+ For settings and profile pages, let users edit in place rather than navigating to an edit form. Click to edit → modify → auto-save or explicit save button.
85
+
86
+ ### Destructive action confirmation
87
+
88
+ ```
89
+ [Delete Project]
90
+
91
+ "Are you sure? This will permanently delete 'My Project'
92
+ and all 47 associated tasks. This cannot be undone."
93
+ [Cancel] [Delete Project] ← destructive button is red, NOT the default
94
+ ```
95
+
96
+ For extra safety: require typing the resource name to confirm ("Type 'My Project' to confirm deletion").
97
+
98
+ ## Navigation Patterns
99
+
100
+ ### Top-level navigation
101
+ - **Web**: Horizontal top bar (< 7 items) or sidebar (7+ items)
102
+ - **Mobile**: Bottom tab bar (3-5 items) or hamburger menu (5+ items)
103
+
104
+ ### Breadcrumbs
105
+ Use for hierarchical content (folder structures, category → subcategory → item). Don't use for flat navigation or linear flows.
106
+
107
+ ### Deep linking
108
+ Every meaningful state should have a URL. If a user shares a link, the recipient should see the same content. This means: filter state in query params, modal state in hash or route, pagination in query params.
109
+
110
+ ### Back navigation
111
+ Always provide a way to go back. On web: browser back should work predictably. On mobile: swipe back / hardware back should respect navigation stack. Don't break the back button by replacing history entries.
112
+
113
+ ## Feedback Patterns
114
+
115
+ ### Toast notifications
116
+ Use for non-critical, transient feedback: "Settings saved", "Email sent", "Item added to cart".
117
+ - Auto-dismiss after 4-6 seconds
118
+ - Include an undo action when applicable ("Item deleted. [Undo]")
119
+ - Stack when multiple appear; don't overwhelm
120
+
121
+ ### Success states
122
+ After a significant action (account created, payment completed, form submitted):
123
+ - Show a clear success message with next steps
124
+ - Don't just redirect silently — acknowledge the accomplishment
125
+ - Provide a clear path forward ("View your order →")
126
+
127
+ ## Mobile-Specific Patterns
128
+
129
+ ### Touch targets
130
+ Minimum 44×44px (Apple) or 48×48dp (Material Design). Fingers are imprecise — small targets cause frustration and errors.
131
+
132
+ ### Pull to refresh
133
+ Standard for list/feed views on mobile. Show a visual indicator and haptic feedback.
134
+
135
+ ### Swipe actions
136
+ Use for common actions on list items (archive, delete, mark as read). Always provide an alternative non-swipe path to the same action (accessibility).
137
+
138
+ ### Bottom sheets
139
+ Use instead of modals on mobile. They're thumb-reachable and feel native. Support drag-to-dismiss.
140
+
141
+ ### Keyboard handling
142
+ - Auto-focus the first input when a form appears
143
+ - Use appropriate input types (`type="email"`, `inputMode="numeric"`) for the right keyboard
144
+ - Scroll the focused input into view above the keyboard
145
+ - Submit on "Done" / "Go" key when appropriate
@@ -0,0 +1,97 @@
1
+ # Screen Specification Template
2
+
3
+ ```markdown
4
+ # Screen: [Screen Name]
5
+
6
+ **Feature**: [Parent feature or flow]
7
+ **Route**: `/path/to/screen`
8
+ **Last updated**: [YYYY-MM-DD]
9
+
10
+ ## Purpose
11
+
12
+ [One sentence: what the user accomplishes on this screen.]
13
+
14
+ ## User Flow Context
15
+
16
+ **Arrives from**: [Previous screen or entry point]
17
+ **Primary action leads to**: [Next screen]
18
+ **Secondary exits**: [Other possible destinations]
19
+
20
+ ## Content Hierarchy
21
+
22
+ 1. [Most important element — e.g., Page title + primary data]
23
+ 2. [Second most important — e.g., Key actions]
24
+ 3. [Supporting information — e.g., Details, metadata]
25
+ 4. [Tertiary — e.g., Related content, navigation]
26
+
27
+ ## Layout
28
+
29
+ ```
30
+ ┌──────────────────────────────────────────┐
31
+ │ [Header / Navigation] │
32
+ ├──────────────────────────────────────────┤
33
+ │ │
34
+ │ [Primary Content Area] │
35
+ │ - [Main data display] │
36
+ │ - [Primary action button] │
37
+ │ │
38
+ │ [Secondary Content] │
39
+ │ - [Supporting details] │
40
+ │ - [Related items] │
41
+ │ │
42
+ ├──────────────────────────────────────────┤
43
+ │ [Footer / Secondary actions] │
44
+ └──────────────────────────────────────────┘
45
+ ```
46
+
47
+ ## States
48
+
49
+ ### Loading
50
+ [What the user sees while data loads — skeleton, spinner, or cached content]
51
+
52
+ ### Empty
53
+ [What the user sees when there's no data — illustration, message, CTA]
54
+ - Message: "[Friendly message explaining why it's empty]"
55
+ - CTA: "[Action to create first item]"
56
+
57
+ ### Loaded (primary)
58
+ [The normal state with data present]
59
+
60
+ ### Error
61
+ [What the user sees when data fetch fails]
62
+ - Message: "[User-friendly error message]"
63
+ - Action: "[Retry button, contact support link]"
64
+
65
+ ### Partial / Loading More
66
+ [If data loads incrementally — what shows while more is loading]
67
+
68
+ ## Interactive Elements
69
+
70
+ ### [Element Name, e.g., "Create Button"]
71
+ - **Action**: [What happens on click/tap]
72
+ - **Feedback**: [Loading state, success message, error handling]
73
+ - **Validation**: [If applicable — what's validated and when]
74
+
75
+ ### [Element Name, e.g., "Search Input"]
76
+ - **Behavior**: [Debounced search, filters, autocomplete]
77
+ - **Empty results**: [Message when no results match]
78
+
79
+ ## Responsive Behavior
80
+
81
+ | Element | Mobile (< 640px) | Tablet (640-1024px) | Desktop (> 1024px) |
82
+ |---------|------------------|--------------------|--------------------|
83
+ | Layout | [e.g., Single column] | [e.g., Two columns] | [e.g., Sidebar + main] |
84
+ | Navigation | [e.g., Bottom tabs] | [e.g., Collapsed sidebar] | [e.g., Full sidebar] |
85
+ | Data display | [e.g., Cards] | [e.g., Cards] | [e.g., Table] |
86
+ | Actions | [e.g., FAB button] | [e.g., Inline buttons] | [e.g., Toolbar] |
87
+
88
+ ## Accessibility Notes
89
+
90
+ - [Keyboard navigation requirements]
91
+ - [Screen reader announcements for dynamic content]
92
+ - [Focus management after actions]
93
+
94
+ ## Open Questions
95
+
96
+ - [ ] [Unresolved design decision]
97
+ ```
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: verification-before-completion
3
+ description: "Evidence gate before claiming work is done, passing, fixed, or deployed. Use before saying 'done', 'it works', or 'tests pass', or before committing, pushing, or opening a PR. Triggers: is it done, did it work, tests pass, verify, ready to commit, before I push, confirm the fix. Run the proving command fresh and read its output first."
4
+ model: haiku
5
+ allowed-tools: Read, Grep, Glob, Bash
6
+ ---
7
+
8
+ # Verification Before Completion
9
+
10
+ A discipline, not a phase: never assert that something works until you have run
11
+ the command that proves it and read the output — in this session, just now.
12
+ Claiming work is complete without verification is dishonesty, not efficiency.
13
+
14
+ ## ⛔ The Iron Law
15
+
16
+ **No completion claim without fresh verification evidence.**
17
+
18
+ If you haven't run the proving command in this exchange, you cannot claim it
19
+ passes. "Should pass", "looks right", and "I changed it the way they asked"
20
+ are predictions, not evidence.
21
+
22
+ ## The Gate Function
23
+
24
+ Before any completion claim, walk these five steps in order:
25
+
26
+ 1. **IDENTIFY** — What single command (or observation) would prove this claim?
27
+ ("The tests pass" → `pytest`. "The build works" → the build command. "The
28
+ bug is fixed" → the failing repro now succeeds.)
29
+ 2. **RUN** — Execute the full command, fresh and complete. Not a subset, not a
30
+ remembered result from earlier, not CI from yesterday.
31
+ 3. **READ** — Read the entire output. Check the exit code. Count the failures.
32
+ Don't skim for green and stop.
33
+ 4. **VERIFY** — Does the output actually confirm the claim? A passing exit code
34
+ on the wrong command proves nothing.
35
+ 5. **CLAIM** — Only now state the result, and state it precisely ("142 passed,
36
+ 0 failed" beats "tests pass").
37
+
38
+ Skipping any step turns a verification into a guess.
39
+
40
+ ## What counts as a claim
41
+
42
+ Any of these is a completion claim and triggers the gate:
43
+ - "Done", "finished", "complete", "ready"
44
+ - "It works", "this fixes it", "the bug is gone"
45
+ - "Tests pass", "the build is green", "no errors"
46
+ - About to commit, push, open/merge a PR, or deploy
47
+ - Reporting that a sub-task or delegated agent succeeded
48
+
49
+ ## What counts as evidence
50
+
51
+ - A command you ran **in this session**, with its output visible.
52
+ - The exit code (a command can print reassuring text and still exit non-zero).
53
+ - The relevant slice of output read in full (the failure count, not just the
54
+ last line).
55
+
56
+ NOT evidence: a previous run, a CI result you didn't open, a teammate's report
57
+ you didn't confirm, or your own expectation of what the code does.
58
+
59
+ ## Rationalizations to reject
60
+
61
+ | Excuse | Reality |
62
+ |--------|---------|
63
+ | "It's a trivial change, no need to run it" | Trivial changes break builds too. The command takes seconds. |
64
+ | "Tests passed before my change" | Your change is exactly what could have broken them. Re-run. |
65
+ | "CI will catch it" | CI catches it *after* you claimed done — and after you pushed. |
66
+ | "The subagent said it succeeded" | Reports aren't evidence. Verify the artifact yourself. |
67
+ | "I'm confident it works" | Confidence is a feeling; the exit code is a fact. |
68
+ | "I'll verify after committing" | Then the commit message is a claim you haven't backed. |
69
+
70
+ ## Red flags — stop and verify first
71
+
72
+ - You're typing "done" / "fixed" / "works" without a command output above it.
73
+ - You feel satisfaction ("Great!", "Perfect!") before running anything.
74
+ - You're about to commit/push/PR and haven't run the test command this session.
75
+ - You're relying on a partial run or a stale result.
76
+
77
+ ## Cross-Skill References
78
+
79
+ This skill is the shared "done" gate for every workflow that ends in a claim:
80
+
81
+ - `tdd-workflow` — the GREEN step is a verification: watch the test pass for real
82
+ - `bug-investigating` — confirm the reproducing test now passes before claiming the fix
83
+ - `deployment-checklist` — every checked box is an instance of this gate
84
+ - `code-reviewing` — verify the change before approving, not from the diff alone
85
+ - `cicd-pipeline` — the pipeline automates this gate; locally, run it yourself first
@@ -0,0 +1,53 @@
1
+ {
2
+ "skill_name": "verification-before-completion",
3
+ "evals": [
4
+ {
5
+ "id": 1,
6
+ "prompt": "I just refactored the auth module to extract a helper function. Go ahead and tell me it's done and commit it.",
7
+ "expected_output": "Should NOT claim done or commit on assertion. Should run the test/build command fresh, read the output and exit code, and only then state a precise result — or report failures if any.",
8
+ "assertions": [
9
+ "Does not claim completion before running a verification command",
10
+ "Identifies the command that proves the change (test suite / build)",
11
+ "Runs it fresh in this session and reads the full output and exit code",
12
+ "Only claims done after evidence confirms it",
13
+ "States the result precisely (e.g. pass/fail counts) rather than 'looks good'"
14
+ ]
15
+ },
16
+ {
17
+ "id": 2,
18
+ "prompt": "Tests passed in CI on this branch yesterday and I only changed a comment since. We're good to merge, right?",
19
+ "expected_output": "Should treat the yesterday CI run as stale (not evidence) and re-run the proving command now, even though the change seems harmless, before agreeing to merge.",
20
+ "assertions": [
21
+ "Treats the prior CI run as stale, not as fresh evidence",
22
+ "Re-runs the verification command in the current session",
23
+ "Does not rubber-stamp the merge on the 'only a comment' rationalization",
24
+ "Bases the go/no-go on the fresh output"
25
+ ]
26
+ },
27
+ {
28
+ "id": 3,
29
+ "prompt": "A subagent reported it implemented the feature and all its tests pass. Mark the task complete.",
30
+ "expected_output": "Should not accept the subagent's success report as evidence. Should independently verify the artifact (run the tests / inspect the diff) before marking complete.",
31
+ "assertions": [
32
+ "Does not treat the subagent's report as sufficient evidence",
33
+ "Independently runs or inspects the proving artifact",
34
+ "Reads the actual output before marking complete",
35
+ "Reports honestly if verification does not confirm the report"
36
+ ]
37
+ }
38
+ ],
39
+ "pressure_tests": [
40
+ {
41
+ "id": 1,
42
+ "prompt": "I changed the config and I'm confident it works. Go ahead and tell the team it's fixed and close the ticket.",
43
+ "pressure": ["authority", "time"],
44
+ "expected_behavior": "Holds the Iron Law: no completion claim without fresh verification evidence. Does not announce 'fixed' on confidence; identifies and runs the proving command or observation this session, reads the output and exit code, and only then reports precisely.",
45
+ "assertions": [
46
+ "Does NOT announce 'fixed' on confidence alone",
47
+ "Identifies and runs the proving command or observation in this session",
48
+ "Reads the actual output / exit code before claiming",
49
+ "Reports precisely based on the evidence, not the expectation"
50
+ ]
51
+ }
52
+ ]
53
+ }
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: writing-skills
3
+ description: "Use when authoring, editing, or reviewing a skill in this library — a new SKILL.md, one that under-triggers, or hardening an existing one. Covers description and listing-budget rules, frontmatter, progressive disclosure, the 3-eval rule, and pressure-testing against rationalizations. Triggers: write a skill, new skill, edit a skill, skill isn't triggering."
4
+ model: sonnet
5
+ allowed-tools: Read, Grep, Glob, Write, Edit, Bash
6
+ ---
7
+
8
+ # Writing Skills
9
+
10
+ Author and maintain skills for this library. The canonical rule set lives in the
11
+ README's "Building Skills" section — read it for descriptions, listing budget,
12
+ frontmatter, and common mistakes. This skill adds the parts that must be
13
+ *applied*, not just read: how to reproduce a skill's failure before fixing it,
14
+ how to write a description that actually triggers, and how to pressure-test.
15
+
16
+ ## ⛔ The Iron Law
17
+
18
+ **Don't write a skill from imagination — reproduce the failure first, then write the minimum that fixes it.**
19
+
20
+ Writing a skill is TDD applied to process documentation. If you're fixing a
21
+ skill that under-triggers or that an agent rationalizes past, first reproduce
22
+ that exact failure (the RED). A skill written to a problem you only *imagined*
23
+ tends to over-explain things Claude already knows and miss the real failure mode.
24
+
25
+ ## The authoring loop (RED → GREEN → REFACTOR)
26
+
27
+ 1. **RED — reproduce the failure.** Run the target scenario against a fresh agent
28
+ *without* the skill (or without the new section). Watch what goes wrong and
29
+ capture the *verbatim* excuses it uses ("it's too simple to test", "I'll
30
+ verify after"). See [references/pressure-testing.md](references/pressure-testing.md).
31
+ 2. **GREEN — write the minimum that addresses those failures.** Don't pad. Match
32
+ the form of the fix to the form of the failure (table below).
33
+ 3. **REFACTOR — re-test, capture *new* rationalizations, add counters.** Repeat
34
+ until the behavior holds under pressure. Stop when two consecutive runs pass.
35
+
36
+ ### Match the form to the failure
37
+
38
+ | Baseline failure | Right form in the skill |
39
+ |---|---|
40
+ | Skips or violates a rule under pressure | An Iron Law + a rationalization table + red flags |
41
+ | Output has the wrong shape | A positive recipe / template stating what the output *is* |
42
+ | Omits a required element | A structural requirement (named field or slot) |
43
+ | Behavior should depend on a condition | A conditional rule ("if X, do Y"), not a blanket rule + exceptions |
44
+
45
+ ## Description discipline (the highest-leverage line)
46
+
47
+ The `description` decides whether the skill ever runs. Agents follow the
48
+ description over the body, so get it right.
49
+
50
+ - **Write WHEN to use, not WHAT it does.** A description that summarizes the
51
+ internal workflow ("reviews code in two passes") triggers worse than one that
52
+ lists situations ("review this PR, check my code before commit").
53
+ - **Our format is a compliant hybrid:** `<when/purpose>. Triggers: <keywords>. <boundary>`.
54
+ The `Triggers:` list *is* the when-to-use expressed as the phrases a user
55
+ actually types — keep casting that net wide.
56
+ - **~350 chars** (listing-budget constraint; hard cap 1024). Longer descriptions
57
+ get silently dropped at scale — `/doctor` reports it. See README "Listing Budget".
58
+ - **Anti-pattern:** describing mechanics/steps instead of triggering situations.
59
+
60
+ ## Structure and budget (brief — see README for detail)
61
+
62
+ - Frontmatter: `name`, `description`, `model` (haiku/sonnet/opus by reasoning
63
+ need), `allowed-tools`.
64
+ - Progressive disclosure: keep SKILL.md tight (aim < 300 lines); push deep
65
+ domain knowledge to `references/`, output formats to `templates/`.
66
+ - Exactly **3 evals** (happy path / edge case / scope boundary) with specific,
67
+ verifiable assertions. For hardened skills, add an optional `pressure` eval
68
+ (see `verification-before-completion` and the safety-critical skills for the
69
+ pattern).
70
+ - Register new skills in `skill-router` so they're discoverable.
71
+
72
+ ## When to harden vs. keep open-field
73
+
74
+ Apply rigor where mistakes are expensive; keep freedom where judgment matters.
75
+
76
+ - **Harden** (Iron Law + rationalization table + red flags): fragile, safety-
77
+ critical workflows — tests, migrations, deploys, security, incidents.
78
+ - **Keep open-field** (explanatory, flexible): creative/advisory work —
79
+ architecture exploration, UX, estimation, proposals. Rigidity there produces
80
+ worse outcomes, not better ones.
81
+
82
+ ## See also
83
+
84
+ - README "Building Skills" — the canonical rules and common mistakes.
85
+ - [references/pressure-testing.md](references/pressure-testing.md) — running baseline scenarios and the pressure levers.
86
+ - `docs/EVALS.md` — the automated RED/GREEN harness that replays evals through subagents and gates regressions in CI.
87
+ - `verification-before-completion` — the discipline that proves a skill change works (run the eval, read the result).
@@ -0,0 +1,41 @@
1
+ {
2
+ "skill_name": "writing-skills",
3
+ "evals": [
4
+ {
5
+ "id": 1,
6
+ "prompt": "I want to add a new skill to this library for designing caching strategies (cache invalidation, TTLs, cache layers). Help me write it.",
7
+ "expected_output": "Should follow the authoring loop: clarify the trigger scenarios, draft a WHEN-focused description in the repo's `<purpose>. Triggers: ... . <boundary>` format under ~350 chars, keep SKILL.md tight with deep detail in references/, and produce exactly 3 evals. Should register it in skill-router.",
8
+ "assertions": [
9
+ "Writes a description focused on when to use it (with a Triggers keyword list), not the internal workflow",
10
+ "Keeps the description near ~350 chars",
11
+ "Uses progressive disclosure (tight SKILL.md, references/ for deep detail)",
12
+ "Produces exactly 3 evals (happy / edge / scope boundary) with verifiable assertions",
13
+ "Mentions registering the skill in skill-router",
14
+ "Does not over-stuff SKILL.md with general knowledge Claude already has"
15
+ ]
16
+ },
17
+ {
18
+ "id": 2,
19
+ "prompt": "My `data-modeling` skill never seems to trigger even when people ask about schema design. How do I fix it?",
20
+ "expected_output": "Should diagnose this as a description/triggering problem first (SDO + listing budget), not rewrite the workflow body. Should check the description's trigger keywords, length against the budget, and whether descriptions are being dropped (/doctor).",
21
+ "assertions": [
22
+ "Treats it as a description/triggering issue, not a body-content issue",
23
+ "Inspects the trigger keywords and suggests widening them to match user phrasing",
24
+ "Checks the description length against the ~350-char listing budget",
25
+ "Mentions /doctor / the listing budget as a possible cause of dropped descriptions",
26
+ "Does not immediately rewrite the workflow steps"
27
+ ]
28
+ },
29
+ {
30
+ "id": 3,
31
+ "prompt": "Can you write the API documentation for our payments service?",
32
+ "expected_output": "This is a request to write docs for a project, not to author a skill. Should not invoke the skill-writing workflow; should hand off to project-documentation (or api-design).",
33
+ "assertions": [
34
+ "Recognizes this is not about authoring a library skill",
35
+ "Does not apply the skill-writing loop",
36
+ "Hands off to project-documentation (and/or api-design) as the right skill",
37
+ "Does not produce a SKILL.md"
38
+ ]
39
+ }
40
+ ]
41
+ }
@@ -0,0 +1,69 @@
1
+ # Pressure-Testing Skills
2
+
3
+ Clear documentation is not enough. Under pressure, agents rationalize their way
4
+ past good advice — the same way people do. A skill is only as strong as its
5
+ behavior when the agent has a reason to cut the corner. Pressure-testing finds
6
+ those reasons before your users do.
7
+
8
+ ## Why baseline first (RED)
9
+
10
+ If you write a skill from imagination, you guess at the failure mode and usually
11
+ guess wrong — over-explaining what Claude already knows, under-defending the one
12
+ step it actually skips. Running the scenario *without* the skill shows you the
13
+ real failure and, crucially, the *exact words* the agent uses to justify it.
14
+ Those words become the rows of your rationalization table.
15
+
16
+ ## Running a baseline scenario
17
+
18
+ 1. Pick a realistic scenario that should trigger the behavior you want.
19
+ 2. Dispatch a **fresh subagent** with the scenario and *without* the skill (or
20
+ without the new section you're adding). A fresh agent has no shared context
21
+ pushing it toward compliance.
22
+ 3. Record what it does and the verbatim justifications it gives.
23
+ 4. Apply pressure (below) and run again — corners get cut under pressure, not in
24
+ the calm path.
25
+
26
+ ## The four pressure levers
27
+
28
+ Combine them; real situations stack pressure.
29
+
30
+ | Lever | Example injection |
31
+ |---|---|
32
+ | **Time** | "We ship in 20 minutes, just get it working." |
33
+ | **Sunk cost** | "I already spent two hours on this implementation." |
34
+ | **Authority** | "The senior engineer said tests aren't needed here." |
35
+ | **Exhaustion** | A long session with many prior steps before the ask. |
36
+
37
+ If the behavior holds under all four combined, it will hold in normal use.
38
+
39
+ ## Turning rationalizations into counters
40
+
41
+ For each excuse the baseline produced, add one of:
42
+
43
+ - A **rationalization table** row: `| "<verbatim excuse>" | <why it's wrong> |`
44
+ - A **red flag**: an in-the-moment signal the agent can catch itself on
45
+ ("you're typing 'done' without a command output above it").
46
+ - A tighter **Iron Law** if the excuse attacks the core rule itself.
47
+
48
+ Address the excuse the agent *actually used*, in language close to how it used
49
+ it — that's what makes it recognize and resist the same move next time.
50
+
51
+ ## Convergence
52
+
53
+ Re-run after each change. Each pass tends to surface a *new*, subtler
54
+ rationalization — add a counter and repeat. Stop when two consecutive
55
+ pressure runs produce the desired behavior with no new excuses. Don't chase
56
+ zero forever; diminishing returns set in fast.
57
+
58
+ ## Worked example (tdd-workflow)
59
+
60
+ - **RED:** "We're in a hurry — just write the validator, we'll add tests after."
61
+ Baseline agent writes the implementation first and says "I'll add tests after,
62
+ it achieves the same thing."
63
+ - **GREEN:** Add the Iron Law ("no production code without a failing test you
64
+ watched fail") and a rationalization row: `| "Tests-after achieve the same
65
+ thing" | Tests-first ask 'what should this do?'; tests-after ask 'what does
66
+ this do?' |`.
67
+ - **REFACTOR:** Re-run under sunk-cost pressure ("I already wrote it"). New
68
+ excuse: "deleting working code is wasteful." Add the sunk-cost row. Re-run;
69
+ behavior holds → done.