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.
- package/LICENSE +21 -0
- package/README.md +144 -0
- package/VERSION +1 -0
- package/bin/cli.mjs +44 -0
- package/catalog.json +225 -0
- package/commands/role.md +34 -0
- package/hooks/session-start.mjs +118 -0
- package/install.mjs +318 -0
- package/package.json +47 -0
- package/roles.json +194 -0
- package/scripts/resolve.mjs +296 -0
- package/skills/accessibility-design/SKILL.md +128 -0
- package/skills/accessibility-design/evals/evals.json +51 -0
- package/skills/accessibility-design/references/accessibility-patterns.md +321 -0
- package/skills/api-design/SKILL.md +144 -0
- package/skills/api-design/evals/evals.json +48 -0
- package/skills/api-design/references/rest-conventions.md +147 -0
- package/skills/api-design/templates/api-spec.md +156 -0
- package/skills/architecture-design/SKILL.md +86 -0
- package/skills/architecture-design/evals/evals.json +44 -0
- package/skills/architecture-design/references/clean-architecture.md +147 -0
- package/skills/architecture-design/references/component-principles.md +129 -0
- package/skills/architecture-design/references/principles.md +81 -0
- package/skills/architecture-design/references/solid-principles.md +106 -0
- package/skills/architecture-design/templates/adr.md +63 -0
- package/skills/architecture-documentation/SKILL.md +126 -0
- package/skills/architecture-documentation/evals/evals.json +44 -0
- package/skills/architecture-documentation/references/abstraction-levels.md +91 -0
- package/skills/architecture-documentation/references/diagram-tooling.md +141 -0
- package/skills/architecture-documentation/templates/architecture-doc.md +171 -0
- package/skills/bug-investigating/SKILL.md +133 -0
- package/skills/bug-investigating/evals/evals.json +56 -0
- package/skills/bug-investigating/references/common-bugs.md +62 -0
- package/skills/bug-investigating/references/debugging-patterns.md +94 -0
- package/skills/cicd-pipeline/SKILL.md +87 -0
- package/skills/cicd-pipeline/evals/evals.json +34 -0
- package/skills/cicd-pipeline/references/pipeline-patterns.md +206 -0
- package/skills/cicd-pipeline/templates/github-actions.md +206 -0
- package/skills/code-reviewing/SKILL.md +92 -0
- package/skills/code-reviewing/evals/evals.json +62 -0
- package/skills/code-reviewing/references/error-handling.md +108 -0
- package/skills/code-reviewing/references/review-checklist.md +144 -0
- package/skills/configuration-strategy/SKILL.md +109 -0
- package/skills/configuration-strategy/evals/evals.json +41 -0
- package/skills/configuration-strategy/references/config-patterns.md +161 -0
- package/skills/containerization/SKILL.md +90 -0
- package/skills/containerization/evals/evals.json +36 -0
- package/skills/containerization/references/dockerfile-patterns.md +168 -0
- package/skills/containerization/templates/dockerfile.md +154 -0
- package/skills/data-modeling/SKILL.md +83 -0
- package/skills/data-modeling/evals/evals.json +43 -0
- package/skills/data-modeling/references/conventions.md +57 -0
- package/skills/data-modeling/templates/schema.md +120 -0
- package/skills/dependency-impact-analysis/SKILL.md +113 -0
- package/skills/dependency-impact-analysis/evals/evals.json +41 -0
- package/skills/dependency-impact-analysis/references/impact-patterns.md +150 -0
- package/skills/dependency-management/SKILL.md +161 -0
- package/skills/dependency-management/evals/evals.json +48 -0
- package/skills/dependency-management/references/evaluation-checklist.md +127 -0
- package/skills/deployment-checklist/SKILL.md +132 -0
- package/skills/deployment-checklist/evals/evals.json +58 -0
- package/skills/deployment-checklist/references/pre-deploy-gates.md +91 -0
- package/skills/deployment-repo/SKILL.md +190 -0
- package/skills/deployment-repo/evals/evals.json +44 -0
- package/skills/deployment-repo/references/deployment-repo-patterns.md +258 -0
- package/skills/deployment-repo/references/version-compatibility.md +227 -0
- package/skills/deployment-repo/templates/deployment-repo-structure.md +226 -0
- package/skills/effort-estimation/SKILL.md +95 -0
- package/skills/effort-estimation/evals/evals.json +32 -0
- package/skills/effort-estimation/references/estimation-methods.md +154 -0
- package/skills/feature-planning/SKILL.md +84 -0
- package/skills/feature-planning/evals/evals.json +44 -0
- package/skills/feature-planning/templates/plan.md +55 -0
- package/skills/feature-planning/templates/task.md +26 -0
- package/skills/frontend-architecture/SKILL.md +154 -0
- package/skills/frontend-architecture/evals/evals.json +34 -0
- package/skills/frontend-architecture/references/component-patterns.md +264 -0
- package/skills/frontend-architecture/templates/folder-structure.md +203 -0
- package/skills/git-workflow/SKILL.md +127 -0
- package/skills/git-workflow/evals/evals.json +44 -0
- package/skills/git-workflow/references/conventions.md +142 -0
- package/skills/git-workflow/templates/pull-request.md +57 -0
- package/skills/gitops-delivery/SKILL.md +319 -0
- package/skills/gitops-delivery/evals/evals.json +44 -0
- package/skills/gitops-delivery/references/gitops-patterns.md +478 -0
- package/skills/gitops-delivery/templates/gitops-config.md +196 -0
- package/skills/incident-response/SKILL.md +130 -0
- package/skills/incident-response/evals/evals.json +55 -0
- package/skills/incident-response/references/communication-templates.md +134 -0
- package/skills/incident-response/references/severity-levels.md +77 -0
- package/skills/incident-response/templates/incident-timeline.md +57 -0
- package/skills/infrastructure-as-code/SKILL.md +86 -0
- package/skills/infrastructure-as-code/evals/evals.json +33 -0
- package/skills/infrastructure-as-code/references/iac-patterns.md +179 -0
- package/skills/infrastructure-as-code/templates/terraform-module.md +158 -0
- package/skills/metrics-and-okrs/SKILL.md +113 -0
- package/skills/metrics-and-okrs/evals/evals.json +33 -0
- package/skills/metrics-and-okrs/references/metric-catalog.md +90 -0
- package/skills/metrics-and-okrs/templates/okr-document.md +61 -0
- package/skills/ml-experiment-tracking/SKILL.md +96 -0
- package/skills/ml-experiment-tracking/evals/evals.json +32 -0
- package/skills/ml-experiment-tracking/references/tracking-tools.md +127 -0
- package/skills/ml-model-deployment/SKILL.md +106 -0
- package/skills/ml-model-deployment/evals/evals.json +34 -0
- package/skills/ml-model-deployment/references/serving-patterns.md +162 -0
- package/skills/ml-pipeline-design/SKILL.md +162 -0
- package/skills/ml-pipeline-design/evals/evals.json +34 -0
- package/skills/ml-pipeline-design/references/pipeline-components.md +174 -0
- package/skills/observability-design/SKILL.md +162 -0
- package/skills/observability-design/evals/evals.json +52 -0
- package/skills/observability-design/references/logging-patterns.md +229 -0
- package/skills/observability-design/references/slo-framework.md +151 -0
- package/skills/observability-design/templates/slo-document.md +80 -0
- package/skills/performance-optimization/SKILL.md +83 -0
- package/skills/performance-optimization/evals/evals.json +47 -0
- package/skills/performance-optimization/references/bottleneck-patterns.md +256 -0
- package/skills/performance-optimization/references/concurrency.md +101 -0
- package/skills/prd-writing/SKILL.md +109 -0
- package/skills/prd-writing/evals/evals.json +33 -0
- package/skills/prd-writing/references/prd-examples.md +132 -0
- package/skills/prd-writing/templates/prd.md +71 -0
- package/skills/prd-writing/templates/rfc.md +79 -0
- package/skills/project-documentation/SKILL.md +104 -0
- package/skills/project-documentation/evals/evals.json +48 -0
- package/skills/project-documentation/references/contributing-guide.md +100 -0
- package/skills/project-documentation/templates/changelog.md +59 -0
- package/skills/project-documentation/templates/readme.md +121 -0
- package/skills/project-proposal/SKILL.md +90 -0
- package/skills/project-proposal/evals/evals.json +31 -0
- package/skills/project-proposal/references/proposal-examples.md +140 -0
- package/skills/project-proposal/templates/proposal.md +76 -0
- package/skills/project-review/SKILL.md +111 -0
- package/skills/project-review/evals/evals.json +42 -0
- package/skills/refactoring/SKILL.md +90 -0
- package/skills/refactoring/evals/evals.json +44 -0
- package/skills/refactoring/references/transformations.md +132 -0
- package/skills/retrospective/SKILL.md +157 -0
- package/skills/retrospective/evals/evals.json +34 -0
- package/skills/retrospective/references/facilitation-guide.md +130 -0
- package/skills/retrospective/templates/post-mortem.md +121 -0
- package/skills/rollback-strategy/SKILL.md +116 -0
- package/skills/rollback-strategy/evals/evals.json +55 -0
- package/skills/rollback-strategy/references/rollback-patterns.md +125 -0
- package/skills/rollback-strategy/templates/rollback-plan.md +69 -0
- package/skills/security-audit/SKILL.md +146 -0
- package/skills/security-audit/evals/evals.json +66 -0
- package/skills/security-audit/references/owasp-top-10.md +167 -0
- package/skills/security-audit/templates/security-report.md +79 -0
- package/skills/skill-router/SKILL.md +171 -0
- package/skills/skill-router/evals/evals.json +39 -0
- package/skills/strategic-review/SKILL.md +106 -0
- package/skills/strategic-review/evals/evals.json +42 -0
- package/skills/strategic-review/templates/full-review-prompt.md +84 -0
- package/skills/tdd-workflow/SKILL.md +147 -0
- package/skills/tdd-workflow/evals/evals.json +58 -0
- package/skills/tdd-workflow/references/test-quality.md +71 -0
- package/skills/technical-debt-review/SKILL.md +113 -0
- package/skills/technical-debt-review/evals/evals.json +41 -0
- package/skills/technical-debt-review/references/debt-taxonomy.md +124 -0
- package/skills/technical-debt-review/templates/debt-audit.md +85 -0
- package/skills/test-data-strategy/SKILL.md +129 -0
- package/skills/test-data-strategy/evals/evals.json +49 -0
- package/skills/test-data-strategy/references/data-generation-patterns.md +341 -0
- package/skills/test-suite-design/SKILL.md +137 -0
- package/skills/test-suite-design/evals/evals.json +69 -0
- package/skills/test-suite-design/references/test-infrastructure.md +175 -0
- package/skills/test-suite-design/references/testing-pyramid.md +140 -0
- package/skills/ui-ux-design/SKILL.md +117 -0
- package/skills/ui-ux-design/evals/evals.json +35 -0
- package/skills/ui-ux-design/references/interaction-patterns.md +145 -0
- package/skills/ui-ux-design/templates/screen-spec.md +97 -0
- package/skills/verification-before-completion/SKILL.md +85 -0
- package/skills/verification-before-completion/evals/evals.json +53 -0
- package/skills/writing-skills/SKILL.md +87 -0
- package/skills/writing-skills/evals/evals.json +41 -0
- package/skills/writing-skills/references/pressure-testing.md +69 -0
- 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.
|