cyc-stack 0.0.0-stage → 0.7.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/.agents/plugins/marketplace.json +12 -0
- package/.claude-plugin/marketplace.json +14 -0
- package/.claude-plugin/plugin.json +17 -0
- package/.codex-plugin/plugin.json +33 -0
- package/.cursor-plugin/marketplace.json +13 -0
- package/.cursor-plugin/plugin.json +19 -0
- package/INSTALL.md +153 -0
- package/LICENSE +21 -0
- package/README.md +436 -2
- package/bin/cyc.mjs +294 -0
- package/catalog/playbooks.json +20 -0
- package/docs/README.md +30 -0
- package/docs/assets/cyc-method-library.svg +39 -0
- package/docs/assets/cyc-overview.svg +44 -0
- package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
- package/docs/assets/cyc-readme-banner.svg +39 -0
- package/docs/assets/cyc-workflow-diagram.svg +415 -0
- package/docs/code-quality.md +42 -0
- package/docs/context.md +40 -0
- package/docs/cyc-method-map.md +58 -0
- package/docs/cyc-workflow.md +188 -0
- package/docs/engineering/code-standards.md +103 -0
- package/docs/engineering/domain-design.md +81 -0
- package/docs/engineering/failure-handling.md +105 -0
- package/docs/impact-analysis.md +70 -0
- package/docs/installation.md +198 -0
- package/docs/onboarding-recovery.md +75 -0
- package/docs/principles.md +49 -0
- package/docs/project-tools.md +108 -0
- package/docs/response-standard.md +202 -0
- package/docs/runtime.md +249 -0
- package/docs/skill-contract.md +70 -0
- package/docs/skill-craft.md +23 -0
- package/docs/validation.md +39 -0
- package/docs/work-assessments.md +180 -0
- package/hooks/claude.json +10 -0
- package/hooks/codex.json +28 -0
- package/hooks/cursor.json +8 -0
- package/methods/cyc-build/SKILL.md +65 -0
- package/methods/cyc-build/references/file-writes.md +11 -0
- package/methods/cyc-challenge/SKILL.md +48 -0
- package/methods/cyc-context/SKILL.md +76 -0
- package/methods/cyc-context/references/evidence.md +27 -0
- package/methods/cyc-context/references/templates.md +54 -0
- package/methods/cyc-context/scripts/evidence.mjs +61 -0
- package/methods/cyc-correct/SKILL.md +43 -0
- package/methods/cyc-deliver/SKILL.md +52 -0
- package/methods/cyc-design/SKILL.md +50 -0
- package/methods/cyc-design/frontend-design/SKILL.md +43 -0
- package/methods/cyc-design/frontend-design/references/color.md +77 -0
- package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
- package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
- package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
- package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
- package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
- package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
- package/methods/cyc-design/frontend-design/references/typography.md +51 -0
- package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
- package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
- package/methods/cyc-error-ledger/SKILL.md +53 -0
- package/methods/cyc-error-ledger/references/entry-format.md +38 -0
- package/methods/cyc-explore/SKILL.md +41 -0
- package/methods/cyc-frame/SKILL.md +49 -0
- package/methods/cyc-impact/SKILL.md +64 -0
- package/methods/cyc-reflect/SKILL.md +48 -0
- package/methods/cyc-remember/SKILL.md +53 -0
- package/methods/cyc-scout/SKILL.md +67 -0
- package/methods/cyc-setup/SKILL.md +60 -0
- package/methods/cyc-teach/SKILL.md +40 -0
- package/methods/cyc-understand/SKILL.md +40 -0
- package/methods/cyc-understand/references/diagnose.md +53 -0
- package/methods/cyc-verify/SKILL.md +87 -0
- package/methods/cyc-verify/references/recipe.md +53 -0
- package/package.json +91 -4
- package/plugin.json +40 -0
- package/rules/cyc-delivery.mdc +33 -0
- package/scripts/baseline-worker.mjs +10 -0
- package/scripts/catalog.mjs +29 -0
- package/scripts/claude-project-hook.mjs +12 -0
- package/scripts/context-review.mjs +600 -0
- package/scripts/host-activation.mjs +66 -0
- package/scripts/install.mjs +387 -0
- package/scripts/onboarding.mjs +110 -0
- package/scripts/packet.mjs +107 -0
- package/scripts/project-tools.mjs +196 -0
- package/scripts/recovery.mjs +66 -0
- package/scripts/response-gate.mjs +105 -0
- package/scripts/response-hook.mjs +237 -0
- package/scripts/response-mode.mjs +12 -0
- package/scripts/run-gate.mjs +264 -0
- package/scripts/runtime.mjs +1832 -0
- package/scripts/source-hash-worker.mjs +5 -0
- package/scripts/source-snapshot.mjs +405 -0
- package/scripts/test-output.mjs +268 -0
- package/scripts/work-review.mjs +326 -0
- package/skills/cyc/SKILL.md +132 -0
- package/skills/cyc/references/playbooks/bug-fix.md +13 -0
- package/skills/cyc/references/playbooks/evaluate.md +13 -0
- package/skills/cyc/references/playbooks/experience.md +7 -0
- package/skills/cyc/references/playbooks/explore.md +9 -0
- package/skills/cyc/references/playbooks/feature.md +14 -0
- package/skills/cyc/references/playbooks/handoff.md +11 -0
- package/skills/cyc/references/playbooks/investigation.md +7 -0
- package/skills/cyc/references/playbooks/performance.md +7 -0
- package/skills/cyc/references/playbooks/plan.md +11 -0
- package/skills/cyc/references/playbooks/refactor.md +12 -0
- package/skills/cyc/references/playbooks/reflect.md +11 -0
- package/skills/cyc/references/playbooks/resume.md +11 -0
- package/skills/cyc/references/playbooks/review.md +9 -0
- package/skills/cyc/references/playbooks/teach.md +11 -0
- package/skills/cyc/references/playbooks/verify.md +7 -0
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Generic tells
|
|
2
|
+
|
|
3
|
+
This is the page a model writes when nobody tells it otherwise. Learn it so you can recognize it in your own output. Score a rendered page by counting the tells present. Three or more: the page is generic, and the repair is a different decision, not a different color. One or two: fix them before extending the treatment.
|
|
4
|
+
|
|
5
|
+
## The default page
|
|
6
|
+
|
|
7
|
+
Layout
|
|
8
|
+
|
|
9
|
+
1. Centered hero: headline, one-sentence subhead, two buttons (filled and outline), everything centered, nothing else in the first viewport.
|
|
10
|
+
2. Three equal cards in a row, each with an icon in a tinted circle, a bold title and two lines of text. Repeated as "features", "services" and "why us".
|
|
11
|
+
3. Every section built the same way: the same max-width container, the same vertical padding, a centered heading and centered subhead, then a grid.
|
|
12
|
+
4. White and light gray (`#f9fafb`, `#f3f4f6`) alternating as the only rhythm.
|
|
13
|
+
5. A testimonials row of three quote cards with avatar circles, and a stats row of four numbers nobody measured (10k+, 99%, 24/7, 4.9 stars).
|
|
14
|
+
6. A footer with four link columns and a copyright line, however small the site.
|
|
15
|
+
|
|
16
|
+
Type
|
|
17
|
+
|
|
18
|
+
7. Inter, Roboto, Poppins, Montserrat, Open Sans or `system-ui` for everything, including the display size.
|
|
19
|
+
8. Display text at 36 to 48 px with default letter-spacing and line-height 1.2, so the headline reads as large body text.
|
|
20
|
+
9. Every heading at the same weight (700) and the same color. No eyebrow label, no italic or secondary voice anywhere.
|
|
21
|
+
10. Centered text everywhere, including paragraphs.
|
|
22
|
+
|
|
23
|
+
Color and surface
|
|
24
|
+
|
|
25
|
+
11. A blue, indigo, teal or violet accent (`#2563eb`, `#6366f1`, `#14b8a6`, `#8b5cf6`), or a two-stop gradient of two of them, on buttons, icons and a highlighted headline word.
|
|
26
|
+
12. Pure white canvas (`#ffffff`), gray text (`#6b7280`) and gray borders (`#e5e7eb`).
|
|
27
|
+
13. Border-radius 12 to 16 px and a soft drop shadow on every box; cards inside cards.
|
|
28
|
+
14. A gradient blob, glass panel or mesh background behind the hero.
|
|
29
|
+
|
|
30
|
+
Imagery and copy
|
|
31
|
+
|
|
32
|
+
15. Emoji as icons, or several icon sets at different stroke widths.
|
|
33
|
+
16. A category illustration (a cup, a camera, a house outline) stretched to hero size, or a stock-style photo unrelated to the copy.
|
|
34
|
+
17. Headlines that could head any business: "Welcome to [Name]", "Quality you can trust", "Your journey starts here", "Crafted with care", "Elevate your experience".
|
|
35
|
+
18. Placeholder specifics: "123 Main Street", "John Doe", "$99/month", "Since 1995", "Lorem ipsum".
|
|
36
|
+
19. A pill badge above the headline reading "✨ Now live" or "New".
|
|
37
|
+
20. The phone layout is the desktop layout stacked: hero text still centered, the three cards now three tall cards.
|
|
38
|
+
|
|
39
|
+
The opposite failure, which the first twenty tells do not catch
|
|
40
|
+
|
|
41
|
+
21. Wall of text: no photograph, rendered object, illustration or color surface at least a quarter of the viewport wide in the first two viewports; sections are type and hairlines on one flat canvas. Good typography does not rescue this; the page reads as a document.
|
|
42
|
+
22. Flat page: every section sits on the same canvas with the same content column; no full-bleed band, no panel, no change of surface for item-like content.
|
|
43
|
+
|
|
44
|
+
## Escaping each tell
|
|
45
|
+
|
|
46
|
+
Each row is a different decision, not a style.
|
|
47
|
+
|
|
48
|
+
| Tell | Replace with |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| 1 Centered hero | An archetype from the [catalog](layout-archetypes.md): a split whose image bleeds to the viewport edge, a full-bleed scene with type set into its quiet area, a typographic poster, a tool-first opening |
|
|
51
|
+
| 2, 3 Equal cards, identical sections | Structure that follows the content: a numbered process as a vertical index list with large numerals; a menu as a two-column price list with hairline rules; work as an editorial grid with one hero item; a comparison as a real table |
|
|
52
|
+
| 4 Gray and white alternation | Rhythm by density and surface: one dark or deeply colored section, one full-bleed image band, one quiet text-only section at a narrow measure |
|
|
53
|
+
| 5 Invented stats and quotes | Specific proof: a real menu with prices, a named project with its brief, a plan table with actual limits. Or nothing |
|
|
54
|
+
| 6 Four-column footer | A footer proportional to the site: one line with the address, hours and a contact, or a short two-column band |
|
|
55
|
+
| 7 to 9 One sans, one weight | A named pairing from [typography](typography.md): display face plus text face plus an eyebrow style; display at 56 to 96 px on desktop with negative tracking; one italic or handwritten accent phrase |
|
|
56
|
+
| 11, 12 Blue accent, white and gray | A palette derived from the subject ([color](color.md)): tinted canvas, deep brand color, one warm or cool accent, ink that is not pure black |
|
|
57
|
+
| 13 Rounded and shadowed | One surface system: hairline borders on a tinted canvas, or flat color blocks, or sharp corners. Shadows only on things that float |
|
|
58
|
+
| 15, 16 Emoji, category clip art | One icon set at one stroke width; photography chosen for a specific subject and cropped for the layout; or no imagery and strong type |
|
|
59
|
+
| 17, 18 Generic copy | Copy made of this business's nouns: the roast, the street, the neighborhood, the service radius, the dish, the camera body, the venue |
|
|
60
|
+
| 19 Pill badge | An eyebrow label that says something ("Open 6:30 to 15:00 · Roasting Thursdays") |
|
|
61
|
+
| 20 Stacked phone | Recompose per archetype: the image gets its own crop, the action comes before the explanation, lists become a compact rhythm |
|
|
62
|
+
| 21 Wall of text | Material from [visual material](visual-material.md): a sourced photograph stored locally, the product rendered as an object (a board, a ticket, a screen), an illustration with depth, texture on the brand surface |
|
|
63
|
+
| 22 Flat page | One full-bleed image or color band, a tinted panel behind item-like content, a dark section with the demonstration in it |
|
|
64
|
+
|
|
65
|
+
## Score sheet
|
|
66
|
+
|
|
67
|
+
Record this in the run evidence for the signature section and for the finished page, at desktop and phone width:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
View: desktop 1440 | phone 390
|
|
71
|
+
Tells present: [numbers] Count: N Verdict: pass (<3) | fail (>=3)
|
|
72
|
+
Material: [kinds present, largest non-text element as % of viewport width in viewports 1 and 2]
|
|
73
|
+
Changed decisions: ...
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Counting is deliberate. It stops "it feels fine" from passing a page a reviewer recognizes as default at a glance. Tell 21 alone fails the page: a document with a good headline is still a document. The count is a self-review, not a measurement of quality; a page can score zero and still be weak, which the [experience review](experience-review.md) exists to catch.
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# Layout archetypes
|
|
2
|
+
|
|
3
|
+
Nine compositions, each with a sketch, a CSS skeleton, when it fits and how it recomposes on a phone. Pick one by name in the decision sheet. Archetype 0 is the default a model produces unprompted; it is not available unless an existing brand system requires it.
|
|
4
|
+
|
|
5
|
+
Column widths below assume a 12-column grid on a 1280 px content width with full bleed allowed outside it.
|
|
6
|
+
|
|
7
|
+
## 0. Centered hero and card grid (banned)
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
[ headline ]
|
|
11
|
+
[ subhead ]
|
|
12
|
+
[ (button) (button) ]
|
|
13
|
+
[ card ] [ card ] [ card ]
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Tells 1, 2 and 3 on the [generic list](generic-tells.md) in one screen. Not an option.
|
|
17
|
+
|
|
18
|
+
## 1. Split with bleed
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
| eyebrow | |
|
|
22
|
+
| DISPLAY HEADLINE | image bleeds to |
|
|
23
|
+
| two-line subhead | the viewport edge |
|
|
24
|
+
| (action) trust · row | and is taller |
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```css
|
|
28
|
+
.hero { display: grid; grid-template-columns: 5fr 7fr; min-height: 80vh; }
|
|
29
|
+
.hero__media { margin-right: calc(50% - 50vw); } /* bleed */
|
|
30
|
+
.hero__media img { width: 100%; height: 100%; object-fit: cover; }
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Fits: a service with one strong photograph of the work or the person. Phone: image first at full width, cropped 4:5, then text; the action stays within the first screen.
|
|
34
|
+
|
|
35
|
+
## 2. Full-bleed scene
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
+----------------------------------------------+
|
|
39
|
+
| eyebrow photo fills |
|
|
40
|
+
| DISPLAY HEADLINE the viewport; |
|
|
41
|
+
| subhead subject sits in |
|
|
42
|
+
| (action) trust · row the right half |
|
|
43
|
+
+----------------------------------------------+
|
|
44
|
+
next section overlaps upward by 64 px
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```css
|
|
48
|
+
.scene { position: relative; min-height: 92vh; display: grid; align-content: center; }
|
|
49
|
+
.scene__img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; object-position: 70% center; }
|
|
50
|
+
.scene__copy { position: relative; max-width: 36rem; padding-inline: 6vw; z-index: 1; }
|
|
51
|
+
.scene__scrim { position: absolute; inset: 0; background: linear-gradient(90deg, var(--canvas) 30%, transparent 70%); }
|
|
52
|
+
.next { margin-top: -4rem; position: relative; }
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The scrim covers only the text half; the subject keeps its detail. Fits: a product with a person in it, hospitality, anything where atmosphere is the promise. Phone: change `object-position` to keep the subject, scrim from the bottom, text at the bottom of the scene. Observed at Undersold.ai.
|
|
56
|
+
|
|
57
|
+
## 3. Typographic poster
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
| EYEBROW |
|
|
61
|
+
| VERY LARGE DISPLAY, |
|
|
62
|
+
| accent word in a second color. |
|
|
63
|
+
| ------------------------------------------------|
|
|
64
|
+
| paragraph in a narrow column | second column |
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```css
|
|
68
|
+
.poster h1 { font-size: clamp(3.5rem, 9vw, 8.5rem); line-height: 0.95; letter-spacing: -0.04em; }
|
|
69
|
+
.poster__cols { display: grid; grid-template-columns: 1fr 1fr; gap: 4rem; border-top: 1px solid var(--line); padding-top: 2rem; }
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
No image in the opening; a full-bleed photograph or rendered object must arrive in section two, within the second viewport, or the page is tell 21. Fits: events, studios, a catalog with a strong name, anything where the name carries more than any available photograph. Not a way to avoid sourcing images. Phone: headline at 44 px, columns stack, the rule stays.
|
|
73
|
+
|
|
74
|
+
## 4. Tool first
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
+---------------------- brand band ----------------------+
|
|
78
|
+
| +----------------- surface card -------------------+ |
|
|
79
|
+
| | eyebrow | |
|
|
80
|
+
| | HEADLINE in display face | |
|
|
81
|
+
| | [ input field ] (action) | |
|
|
82
|
+
| | one line of reassurance | |
|
|
83
|
+
| +---------------------------------------------------+ |
|
|
84
|
+
+--------------------------------------------------------+
|
|
85
|
+
| results / list / plans directly beneath |
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```css
|
|
89
|
+
.band { background: var(--brand); padding-block: 4rem 6rem; }
|
|
90
|
+
.tool { background: var(--surface); max-width: 48rem; padding: 2.5rem; border-radius: var(--radius); }
|
|
91
|
+
.tool form { display: grid; grid-template-columns: 1fr auto; gap: 0.75rem; }
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The main action is the opening; explanation follows. Fits: catalogs, registrations, quote finders, anything the visitor came to use. Phone: the card fills the width with 16 px gutters; the input and button stack. Observed at ahs.com (zip-code input beside the primary action).
|
|
95
|
+
|
|
96
|
+
## 5. Editorial grid
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
| hero item (8 cols) | item (4) |
|
|
100
|
+
| | item (4) |
|
|
101
|
+
| item (4) | item (4) | item (4) |
|
|
102
|
+
| caption in eyebrow style under each item |
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
```css
|
|
106
|
+
.work { display: grid; grid-template-columns: repeat(12, 1fr); gap: 1.5rem; }
|
|
107
|
+
.work > * { grid-column: span 4; }
|
|
108
|
+
.work > :first-child { grid-column: span 8; grid-row: span 2; }
|
|
109
|
+
.work img { width: 100%; aspect-ratio: 4 / 3; object-fit: cover; }
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
One item leads; the others are secondary on purpose. Fits: portfolios, menus with photographs, project lists. Phone: the lead item full width, the rest in a two-column grid, captions kept.
|
|
113
|
+
|
|
114
|
+
## 6. Sidebar workspace
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
| brand | breadcrumb status · avatar |
|
|
118
|
+
| nav item | eyebrow date |
|
|
119
|
+
| nav item | Display greeting, italic accent. |
|
|
120
|
+
| nav item | [ ring chart card ] [ photo action card ] |
|
|
121
|
+
| | [ stat ] [ stat ] [ note ] |
|
|
122
|
+
| footer | list of records with small photos |
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
```css
|
|
126
|
+
.app { display: grid; grid-template-columns: 240px 1fr; min-height: 100vh; }
|
|
127
|
+
.main { padding: 2rem 3rem; display: grid; gap: 2rem; }
|
|
128
|
+
.row-2 { display: grid; grid-template-columns: 1.3fr 1fr; gap: 1.5rem; }
|
|
129
|
+
.row-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1.5rem; }
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Cards differ in content shape (a chart, a photo with a button, a number with a sentence); same-shaped cards are tell 2. Fits: dashboards, daily tools. Phone: the sidebar becomes a five-item bottom bar, rows stack, the greeting stays in the display face. Observed in Rep & Plate.
|
|
133
|
+
|
|
134
|
+
## 7. Stacked bands
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
| canvas band: headline + image |
|
|
138
|
+
| brand-dark band: the one statement, 3 facts |
|
|
139
|
+
| full-bleed image band with a caption |
|
|
140
|
+
| canvas band: plan table |
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
```css
|
|
144
|
+
.band { padding-block: clamp(4rem, 10vw, 8rem); }
|
|
145
|
+
.band--dark { background: var(--brand); color: var(--canvas); }
|
|
146
|
+
.band--image { padding: 0; aspect-ratio: 21 / 9; }
|
|
147
|
+
.band > .inner { max-width: 80rem; margin-inline: auto; padding-inline: clamp(1rem, 5vw, 4rem); }
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Each band has its own internal grid and its own density. Fits: service sites with several audiences, long marketing pages. Phone: bands keep their surfaces; the image band becomes 4:5.
|
|
151
|
+
|
|
152
|
+
## 8. Sticky panel scroll
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
| sticky: eyebrow | step 01 title, text |
|
|
156
|
+
| HEADLINE | step 02 title, text |
|
|
157
|
+
| (action) | step 03 title, text |
|
|
158
|
+
| | step 04 title, text |
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
```css
|
|
162
|
+
.steps { display: grid; grid-template-columns: 5fr 7fr; gap: 4rem; }
|
|
163
|
+
.steps__panel { position: sticky; top: 6rem; align-self: start; }
|
|
164
|
+
.step { display: grid; grid-template-columns: 4rem 1fr; padding-block: 2.5rem; border-top: 1px solid var(--line); }
|
|
165
|
+
.step__num { font-family: var(--display); font-size: 2.5rem; }
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Fits: a process, a menu by category, a gallery with a persistent caption. Phone: the panel unsticks and sits above the list.
|
|
169
|
+
|
|
170
|
+
## 9. Index list
|
|
171
|
+
|
|
172
|
+
```text
|
|
173
|
+
| 01 | Flat white | Two shots, textured milk | 4.20 |
|
|
174
|
+
| 02 | Cortado | Equal parts, 4 oz glass | 3.90 |
|
|
175
|
+
| 03 | Filter, Kiambu | Washed, black tea, stone fruit | 4.50 |
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
```css
|
|
179
|
+
.index__row { display: grid; grid-template-columns: 3rem 1fr 2fr auto; gap: 1.5rem; padding-block: 1.25rem; border-bottom: 1px solid var(--line); align-items: baseline; }
|
|
180
|
+
.index__num { font-family: var(--display); font-size: 1.5rem; color: var(--ink-muted); }
|
|
181
|
+
.index__price { font-variant-numeric: tabular-nums; }
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The list is the design; no cards. Fits: menus, services, schedules, specifications. Phone: number and title on one line, description beneath, price right-aligned on the first line.
|
|
185
|
+
|
|
186
|
+
## Combining
|
|
187
|
+
|
|
188
|
+
A page uses one opening archetype (1 to 4) and one or two content archetypes (5 to 9). Changing archetype between sections is the rhythm; repeating one archetype with different content is tell 3.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Reference standards
|
|
2
|
+
|
|
3
|
+
Four sites held up as the bar, inspected on 2026-11-02 in a desktop browser with computed styles read from the page where possible. Each entry records what was observed and the rule to transfer. Transfer the mechanism, not the colors; copying a palette produces a costume, not a design.
|
|
4
|
+
|
|
5
|
+
## Undersold.ai (resume and career product)
|
|
6
|
+
|
|
7
|
+
Observed: canvas `#f8f5ee`, ink `#171b18`, brand green `#104034`, gold accent `#e5a128` and `#805000`, mint `#9ce4c6` for small marks. Display in DM Serif Display at 50 px with tracking −1.75 px and line height 1.03; body in DM Sans 16 px. One handwritten phrase per heading ("prove it.") in Kalam, gold, with a hand-drawn underline. Tracked uppercase eyebrow in gold above the headline ("FREE SCORE + BASELINE + GUIDED INTERVIEW + REBUILD"). Full-bleed photograph of a person at a laptop, scrim only over the text half. Primary action in brand green with an arrow; secondary as an outlined "See how it works" with a play icon; a three-item trust row beneath (every bullet scored, baseline yours to keep, no credit card). An open-beta notice in plain words. Dark green band next with a product screenshot in a browser frame. Pricing as three cards where the featured plan is the dark card with a gold header; prices as oversized serif numerals.
|
|
8
|
+
|
|
9
|
+
Transfer: the opening answers "what is this and what do I get" in eyebrow, headline, two sentences and a trust row, with a photograph that has a subject. One accent voice per heading. The dark section is the product demonstration. The featured plan is the one that looks different.
|
|
10
|
+
|
|
11
|
+
## Rep & Plate (daily health tool, product name Fuel)
|
|
12
|
+
|
|
13
|
+
Observed: sidebar workspace (archetype 6). Canvas `#f8faf7` to `#fbfdfb`, brand `#17674e`, ink `#102333`, sage tints for surfaces. Display in Lora with the second phrase in italic muted green ("Your day, *taken care of.*"); body in DM Sans. Eyebrow date in tracked caps. First row: a nutrition card with a ring chart and three macro bars beside a dark photographic workout card with its own action. Second row: three stat cards that differ in content (steps with a sentence, sleep as 7h 12m with mixed numeral sizes, a "2 little things to check" note on a tinted surface). Records listed with small food photographs and "Estimated · editable" under each. Status pill "LOCAL DEMO" in the header. Phone: five-item bottom bar, chat as the primary surface, suggestion chips, "Just on this device" line under the input.
|
|
14
|
+
|
|
15
|
+
Transfer: cards differ by content shape, not by icon. Real-looking records with honest labels beat invented stats. The warm voice lives in the display line and the one-sentence notes, not in every label. Demo state is declared where a visitor could mistake it for a save.
|
|
16
|
+
|
|
17
|
+
## Atlassian.com (software marketing)
|
|
18
|
+
|
|
19
|
+
Observed: one blue (`#0052cc` family) on white, a geometric sans at one weight for headings, a short headline ("Discover the power of knowing"), a pill primary button and a text link with an arrow as the secondary. The hero's second half is a dense, real product screenshot, not an illustration. A logo strip with gray logos. A dark section ("Connect the work behind the work") with a node-graph illustration on the right and the copy on the left. Sections change surface (white, dark, light tint) and density, not just background stripe.
|
|
20
|
+
|
|
21
|
+
Transfer: restraint is a decision; one color used with authority reads as a system. Show the real product at readable size. Change density and surface between sections.
|
|
22
|
+
|
|
23
|
+
## AHS.com (American Home Shield, home warranty)
|
|
24
|
+
|
|
25
|
+
Observed: utility bar, then header with an outlined "Log in" and a filled "Shop Plans" pill. A red promotional band with an icon and one sentence. The hero is a white rounded card on pale blue holding a serif display in red and navy ("Fall is here. Savings are too. 50% off select plans"), two sentences, and a zip-code input joined to a "Shop Plans" button (archetype 4). An awards strip of badges beneath. Plan comparison as three cards where the middle one carries a "Most Popular" header and a highlighted border; each lists specific limits ($50,000 total limit per agreement term, $5,000 per covered HVAC system). Curved section dividers. A photograph of a technician in a branded jacket at a red door.
|
|
26
|
+
|
|
27
|
+
Transfer: when the visitor came to buy or request, the input is the hero. Plans are compared with real numbers. Proof is specific (limits, awards, a technician at a real door), not "trusted by thousands".
|
|
28
|
+
|
|
29
|
+
## Reading these together
|
|
30
|
+
|
|
31
|
+
| Site | Opening mechanism | Type character | Proof |
|
|
32
|
+
| --- | --- | --- | --- |
|
|
33
|
+
| Undersold.ai | Scene with a person, scrim on the text half, trust row | Serif display with one handwritten accent | Product screenshot in a dark band; plan numerals |
|
|
34
|
+
| Rep & Plate | Workspace with a greeting line and content-shaped cards | Serif display with an italic second voice | Real-looking records with honest labels |
|
|
35
|
+
| Atlassian | Short headline, one blue, real product screenshot | One geometric sans, one weight | Logo strip; product at readable size |
|
|
36
|
+
| AHS | Input beside the primary action inside a card | Serif display in brand colors | Plan limits in dollars; awards; technician photo |
|
|
37
|
+
|
|
38
|
+
None of the four opens with a centered headline over three cards, uses a system sans at display size, or relies on an icon-in-a-circle grid. That is the bar.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Typography
|
|
2
|
+
|
|
3
|
+
Type is the fastest way to leave the default page. Choose a pairing by the character the product needs, set the display size and tracking by the numbers below, and load the fonts so they actually render.
|
|
4
|
+
|
|
5
|
+
## Pairings
|
|
6
|
+
|
|
7
|
+
All are free on Google Fonts and as `@fontsource` packages. Character notes say what the pairing does, not what it is "for"; choose against the decision sheet's premise.
|
|
8
|
+
|
|
9
|
+
| Display | Text | Character | Fits |
|
|
10
|
+
| --- | --- | --- | --- |
|
|
11
|
+
| DM Serif Display | DM Sans | High-contrast serif with tight tracking; confident, editorial, warm when set on cream | Services that sell judgment: careers, finance, consulting, premium local trades |
|
|
12
|
+
| Lora (regular and italic) | DM Sans | Calm book serif; the italic reads as a second, softer voice | Health, food, daily tools, anything that should feel taken care of |
|
|
13
|
+
| Fraunces | Inter Tight or Work Sans | Soft "wonky" serif with optical sizes; cozy without being cute | Cafés, bakeries, craft products, small hospitality |
|
|
14
|
+
| Playfair Display | Source Sans 3 | Classic high-contrast; luxury if restrained, costume if overused | Photography, weddings, galleries, hotels |
|
|
15
|
+
| Cormorant Garamond (500 to 600) | Manrope | Delicate, long ascenders; needs size to work (72 px and up) | Fine dining, perfume, art, editorial covers |
|
|
16
|
+
| Instrument Serif | Instrument Sans | Narrow, modern serif; tech with taste | Software with a point of view, studios, agencies |
|
|
17
|
+
| Newsreader | Public Sans | Journal serif with real italics; long-form comfort | Blogs, documentation with voice, reports |
|
|
18
|
+
| Libre Caslon Text | Karla | Bookish and even; quiet authority | Education, nonprofits, archives |
|
|
19
|
+
| Space Grotesk | IBM Plex Sans + IBM Plex Mono | Geometric with quirks; engineering honesty | Catalogs, data tools, developer products |
|
|
20
|
+
| Bricolage Grotesque (700 to 800) | Figtree | Friendly, slightly condensed, punchy at size | Local services, home repair, community events |
|
|
21
|
+
| Archivo Black or Archivo Expanded | Archivo | Heavy industrial grotesque | Workshops, trades, sports, bold retail |
|
|
22
|
+
| Syne (800) | Inter | Wide, poster-like, a little strange | Festivals, music, art events |
|
|
23
|
+
| Bebas Neue | Barlow | Tall condensed caps; loud and cheap in a good way | Events, gyms, schedules, menus on walls |
|
|
24
|
+
| Epilogue (variable) | Epilogue | One family, 100 to 900; wide headings, clean text | Dashboards and apps that want one voice |
|
|
25
|
+
|
|
26
|
+
Not for display: Inter, Roboto, Poppins, Montserrat, Open Sans, Lato, `system-ui`. They are tell 7 on the [generic list](generic-tells.md). Inter or a system stack is acceptable as the text face in a dense tool when the decision sheet says why.
|
|
27
|
+
|
|
28
|
+
One accent voice per page, at most: a Kalam or Caveat phrase, or the display face's italic, on the two or three words that carry the promise. On every heading it stops being an accent.
|
|
29
|
+
|
|
30
|
+
## Numbers
|
|
31
|
+
|
|
32
|
+
| Role | Desktop | Phone | Tracking | Line height |
|
|
33
|
+
| --- | --- | --- | --- | --- |
|
|
34
|
+
| Display (page opening) | 56 to 96 px, `clamp(2.75rem, 6vw, 6rem)` | 36 to 44 px | −0.02 em to −0.04 em | 0.95 to 1.1 |
|
|
35
|
+
| Section heading | 32 to 44 px | 28 to 32 px | −0.01 em to −0.02 em | 1.1 to 1.2 |
|
|
36
|
+
| Body, marketing | 17 to 19 px | 16 to 17 px | 0 | 1.5 to 1.65 |
|
|
37
|
+
| Body, dense tool | 14 to 16 px | 14 to 15 px | 0 | 1.4 to 1.5 |
|
|
38
|
+
| Eyebrow label | 11 to 13 px, uppercase | same | +0.08 em to +0.14 em | 1 |
|
|
39
|
+
| Caption, meta | 12 to 13 px | same | 0 to +0.02 em | 1.3 |
|
|
40
|
+
|
|
41
|
+
- Measure: body 55 to 72 characters; a display headline at most 12 words and about 20 characters wide per line, so it wraps on purpose.
|
|
42
|
+
- Weight: serif display faces usually at 400 to 500; one heavy weight on the page, not three.
|
|
43
|
+
- Oversized numerals: index numbers (01, 02), prices and the one real statistic set in the display face at display size. `font-variant-numeric: tabular-nums` on any column of numbers.
|
|
44
|
+
- Hierarchy test: screenshot at 25% zoom. If display, heading, body and eyebrow are not distinguishable as four roles, the scale is too flat.
|
|
45
|
+
|
|
46
|
+
## Loading
|
|
47
|
+
|
|
48
|
+
- Local-only sites: `npm i @fontsource/<name>` and import the weights used, or copy the woff2 files into `/fonts` with `@font-face { font-display: swap; }`. Do not link Google Fonts on a site that must work offline.
|
|
49
|
+
- Networked sites: the Google Fonts `<link>` with `display=swap`, two families at most, only the weights used.
|
|
50
|
+
- Declare a fallback stack with `size-adjust` so the layout holds before the web font arrives, and render the page once with the font blocked to confirm nothing breaks.
|
|
51
|
+
- Verify in the rendered page (`document.fonts.check` or the computed style) that the display face loaded. A pairing chosen in the decision sheet and silently replaced by Times is the worst outcome on this list.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Apply established UX principles to the chosen visual idea
|
|
2
|
+
|
|
3
|
+
Use while planning and reviewing the relevant frontend flow. Preserve the product's character while making its choices understandable and usable. The principles below support judgment; they do not prove that a particular reference, design or implementation works. Sources were consulted on 2026-11-02.
|
|
4
|
+
|
|
5
|
+
## Direct attention and group meaning
|
|
6
|
+
|
|
7
|
+
Use relative scale, spacing, alignment, contrast and grouping to establish a reading/action order. Visually connect related information and distinguish different jobs. Balance the amount and placement of visual weight; symmetry is optional. Inspect the composition at ordinary reading size as well as a small overview. These decisions adapt [NN/g's visual-design principles](https://www.nngroup.com/articles/principles-visual-design/).
|
|
8
|
+
|
|
9
|
+
For this product, identify the primary decision, its supporting evidence and the next action. Make that relationship visible. Emphasis should reflect importance rather than making every heading large or every block a card. A decoration can be prominent when it contributes meaning; judge the whole composition rather than applying a density quota.
|
|
10
|
+
|
|
11
|
+
## Make the interaction understandable and recoverable
|
|
12
|
+
|
|
13
|
+
The following review questions adapt [Nielsen's usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/):
|
|
14
|
+
|
|
15
|
+
| Principle | Design decision | Verify in the relevant flow |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| Familiar language and recognition | Use the audience's terms, visible options and consistent action patterns | Can someone choose the next step without remembering hidden instructions or decoding an invented control? |
|
|
18
|
+
| Visible status | Show the current selection, progress and actual outcome | Do loading, saving, failure and completion accurately reflect the underlying operation? |
|
|
19
|
+
| Control and recovery | Provide appropriate cancel, back, edit or undo; preserve useful input | Can someone correct a mistake without losing unrelated work or repeating an effect? |
|
|
20
|
+
| Prevention before repair | Explain relevant requirements and constrain invalid choices | Can an invalid or unavailable option lead to a misleading success? |
|
|
21
|
+
|
|
22
|
+
Reduce competing decisions where they impede this task; keep important choices discoverable. Do not hide the central function to make the page look cleaner. A novelty treatment should not require learning a new navigation convention without a product reason.
|
|
23
|
+
|
|
24
|
+
## Keep visual treatment accessible
|
|
25
|
+
|
|
26
|
+
Use the project's applicable accessibility target. For work targeting WCAG 2.2, the following are concrete considerations, not a complete conformance checklist. Read the linked criterion for its exact scope and exceptions when a boundary case matters.
|
|
27
|
+
|
|
28
|
+
| Concern | Implementation and check | Primary source |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| Text on photos, gradients or translucent surfaces | Check actual rendered backgrounds and interaction states. AA text contrast is generally at least 4.5:1, or 3:1 for qualifying large text, with stated exceptions. | [Contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) |
|
|
31
|
+
| Small or crowded controls | Make pointer targets practical to activate. SC 2.5.8 uses 24×24 CSS pixels or applicable exceptions such as sufficient spacing; do not incorrectly call 44×44 a universal AA rule. Larger touch targets can still be a good design choice. | [Target size minimum](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) |
|
|
32
|
+
| Enlarged text and narrow views | Preserve content and functionality when reflowing at 320 CSS pixels for vertical content, with the criterion's exceptions for inherently two-dimensional parts. Inspect zoom and content rather than only page width. | [Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) |
|
|
33
|
+
| Floating navigation, chat and banners | Follow the keyboard path and ensure author-created layers do not entirely hide the focused component; prefer keeping it fully visible. | [Focus not obscured](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) |
|
|
34
|
+
| Automatic tours and moving compositions | Provide pause/stop/hide or update controls when the criterion applies. For nonessential automatic motion alongside other content lasting more than five seconds, a decorative label or reduced-motion mode alone is not a substitute for the required control. | [Pause, stop, hide](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) |
|
|
35
|
+
| Styled forms and compact input/action groups | Supply visible labels or necessary instructions. An accessible name alone does not establish visible input guidance; labels also need correct programmatic association. | [Labels or instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) |
|
|
36
|
+
|
|
37
|
+
Keep semantic controls, meaningful alternatives, logical keyboard order and appropriate focus behavior while composing visual layers. Choose project-supported tools for access checks and inspect the journey manually where needed. A screenshot can suggest a question; it cannot establish keyboard operation, semantics or conformance. Automated results are limited to the rules and states actually exercised.
|
|
38
|
+
|
|
39
|
+
## Preserve character under real conditions
|
|
40
|
+
|
|
41
|
+
Check the chosen idea with representative long content, a missing or delayed asset, first use and a relevant failure state. On phones, preserve the meaning of the subject and primary action while rearranging secondary layers. Avoid simply scaling down the desktop composition or removing every expressive detail. Reserve media space and choose suitable assets so the interface remains usable as content loads; measure any performance claim with the project's tools rather than inferring it from the screenshot.
|
|
42
|
+
|
|
43
|
+
Use a concrete critique: observation → affected user/task → smallest repair → recheck. A photo layer that obscures a label calls for crop, positioning or surface changes; it does not automatically invalidate photography. A product preview that cannot be understood at the displayed size may need a focused crop or interactive explanation rather than more ornament.
|
|
44
|
+
|
|
45
|
+
The [experience review](experience-review.md) records visual judgment, behavior checks, access observations and actual user acceptance separately. No fixed palette, font blacklist, universal card ban or requirement to maximize originality follows from these principles.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Visual material
|
|
2
|
+
|
|
3
|
+
A page made only of type and hairlines is a document, not a website. Every site held up as the bar carries visual material in every viewport: a photograph with a person in it, a product screenshot in a frame, a technician at a door, a ring chart beside a photo card. "No imagery and strong type" is a valid opening for one viewport; it is not a valid page. This reference says what counts, how much, and how to get it when the brief says local only.
|
|
4
|
+
|
|
5
|
+
## The density rule
|
|
6
|
+
|
|
7
|
+
Measured on the desktop render, checked again on the phone:
|
|
8
|
+
|
|
9
|
+
- In each of the first two viewports, at least one non-text element at least 25 percent of the viewport width: a photograph, an illustration with depth, a rendered object (a ticket, a menu board, a map, a product panel), or a color surface holding content.
|
|
10
|
+
- Across the full page, at least three kinds of material from the list below, and at least one full-bleed band (image or color) that breaks the content column.
|
|
11
|
+
- No run of more than two consecutive sections that are text on the flat canvas.
|
|
12
|
+
|
|
13
|
+
A page that fails this is tell 21 on the [generic list](generic-tells.md) however good its type is.
|
|
14
|
+
|
|
15
|
+
## Kinds of material, strongest first
|
|
16
|
+
|
|
17
|
+
| Kind | What it does | Local-only path |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| Photograph with a subject | Puts a person, a place or the work in the room; the single biggest difference between a site and a document | Download under a permissive license and store in `/assets` with source and license noted (below) |
|
|
20
|
+
| Product or interface rendered as an object | A ticket, a chalkboard, a receipt, a schedule card, an app screen in a device frame; proves the thing exists | Build it in HTML and CSS with the page's own tokens; it is content, not decoration |
|
|
21
|
+
| Illustration with depth | A scene, not an icon: layered shapes, a horizon, shadow, texture, a drawn object at the size it would be | Inline SVG of 40 or more paths, or a generated bitmap when an image tool is available |
|
|
22
|
+
| Color surface holding content | A dark band, a brand block with a list inside it, a panel behind a form | CSS only; one dark band per light page, plus tinted panels where content is item-like |
|
|
23
|
+
| Texture | Paper grain, a subtle noise, a halftone, a printed-ink edge; makes flat color feel like a material | CSS: an SVG `feTurbulence` filter at 4 to 8 percent opacity, or a repeating gradient; never a stock "mesh" blob |
|
|
24
|
+
| Map or diagram | Where the place is, how the process runs | Inline SVG drawn from the real streets or steps |
|
|
25
|
+
| Data drawn as a mark | A ring, a bar, a sparkline beside a number | Inline SVG, sized to the number it explains |
|
|
26
|
+
|
|
27
|
+
Icons are not material. A row of icons in circles is tell 2.
|
|
28
|
+
|
|
29
|
+
## Getting photographs when everything must stay local
|
|
30
|
+
|
|
31
|
+
"Local" means the site runs without a server and without hot-linking. It does not mean the build may not fetch an asset once and store it.
|
|
32
|
+
|
|
33
|
+
1. Search a permissive source. Wikimedia Commons answers without a key and returns the license with each file (checked 2026-11-02): `https://commons.wikimedia.org/w/api.php?action=query&generator=search&gsrsearch=<subject>&gsrnamespace=6&gsrlimit=10&prop=imageinfo&iiprop=url|extmetadata&format=json`; read `LicenseShortName` and keep CC0, CC BY and CC BY-SA with attribution. Openverse (`https://api.openverse.org/v1/images/?q=<subject>&license=cc0,by`) is a second source when reachable; it was not from the checking machine. The project's own asset folder comes first when it has anything usable.
|
|
34
|
+
2. Pick for the composition, not the subject alone: where is the quiet area for text, is the subject sharp, does the light match the palette temperature. Reject anything that looks like a stock handshake. Open the downloaded file at full size and look for a watermark, a photographer's logo, a border or a caption baked into the pixels; a mark that is faint in a thumbnail is obvious across a full-bleed band, and a second copy of the same photograph on another host may carry it too.
|
|
35
|
+
3. Fetch the file into `/assets/<name>.jpg`, resize to the largest displayed width (1600 px is enough for a full-bleed), and write `/assets/SOURCES.md` with the URL, author and license for each.
|
|
36
|
+
4. Set `width`, `height` and `object-position` for the desktop and phone crops, and one treatment for every photograph on the site (warm, duotone, hairline, untouched).
|
|
37
|
+
|
|
38
|
+
When an image-generation tool is available in the host, use it for a specific brief ("a two-group espresso machine on an oak counter, morning light from the left, quiet space on the right third") and store the result the same way. When neither is possible, say so in the decision sheet and compensate with rendered objects and illustration with depth, not with more paragraphs.
|
|
39
|
+
|
|
40
|
+
## What this looked like when it went wrong
|
|
41
|
+
|
|
42
|
+
A café page built under a "no external images" instruction chose the typographic poster, set a fine headline and a menu as an index list, and shipped nothing but text and rules from top to bottom: no counter, no bread, no board, no room. It scored zero on the original tells and still read as a document. The fix was not a photograph alone; it was a chalkboard rendered as a dark panel for the day's board, a photograph of the counter bleeding off the right edge, a drawn map in the footer and a textured brand band behind the order form.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-error-ledger
|
|
3
|
+
description: "Retain searchable failure history with causes, attempted fixes, results and regression evidence. Use when diagnosing a reported bug, error or log, when an attempted fix fails, and when recording its resolution."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Error ledger
|
|
7
|
+
|
|
8
|
+
Before debugging anything, ask the ledger: "Have we seen this, and what did we already try?" After debugging, write down what you learned, **especially the fixes that failed**. A failed fix is the most expensive thing to rediscover.
|
|
9
|
+
|
|
10
|
+
For a controller run, `run next` returns `projectLedgerPath` for shared-history lookup and `ledgerPath` for recording. Usually they match: explicit `context.ledgerPath`, otherwise existing `INCIDENT-LEDGER.md`, otherwise `docs/context/error-ledger.md`. When the shared path is outside permitted writes, new runs select `.cyc/runs/ID/error-history.md` and explain why. Search existing shared history and relevant earlier run-local histories; write only the selected target. Create it if absent using [references/entry-format.md](references/entry-format.md). Preserve existing formats; do not create a competing shared ledger.
|
|
11
|
+
|
|
12
|
+
Run-local history is retained evidence, not an update to the shared project log. Disclose that distinction; later promotion needs authorized scope. Do not expand scope, change configuration, or override a project rule requiring a shared/committed record. Outside a controller run, use the same shared-ledger preference and respect the task's write permissions. Update a context index only when useful and authorized.
|
|
13
|
+
|
|
14
|
+
## Look up: first step on any bug, error, or log
|
|
15
|
+
|
|
16
|
+
1. **Make a signature.** Take the error's stable core: error type plus message with the variable parts removed (IDs, timestamps, paths, line numbers), plus the throwing function or area. `TypeError: Cannot read properties of undefined (reading 'finished') @ loadAll`.
|
|
17
|
+
2. **Search shared history and relevant `.cyc/runs/*/error-history.md` files** for the error type, key message words, and area or file. Search loosely; the same bug can surface with different wording. Run-local files may exist only in this checkout; do not imply another checkout has them.
|
|
18
|
+
3. **On a match, read the whole entry before doing anything.** Then:
|
|
19
|
+
- **Resolved, same cause:** it has regressed. Check whether the recorded fix or its regression test was removed or bypassed. Start there.
|
|
20
|
+
- **Resolved, different cause:** a new entry, linked to the old one.
|
|
21
|
+
- **Open:** continue from the recorded attempts. Do not retry a failed fix unless you can state what is different now.
|
|
22
|
+
4. **No match:** say so, and continue with the [diagnose branch](../cyc-understand/references/diagnose.md).
|
|
23
|
+
|
|
24
|
+
## Record: as attempts happen, not only at the end
|
|
25
|
+
|
|
26
|
+
- **Open an entry** as soon as the red loop reproduces the error, with status `open`.
|
|
27
|
+
- **Append every fix attempt** when it is tried: what was changed, the hypothesis behind it, and the result. A failed attempt gets why it failed, with evidence (the command output that stayed red).
|
|
28
|
+
- **On resolution:** record the root cause, the fix commit, the regression test that now guards it, and set status `resolved`.
|
|
29
|
+
- **Can't fix it now:** leave it `open` with the best current understanding, or `wont-fix` with the reason and who decided.
|
|
30
|
+
|
|
31
|
+
Record failures even if the task was abandoned. Unlike context docs, the ledger values dead ends from unfinished work.
|
|
32
|
+
|
|
33
|
+
Finalize resolved entries before final verification. Record covered-file evidence when the fix is not committed; do not invent a commit. New implementation runs with failures, and all bug-fix runs, must reference the selected `ledgerPath` in their [Deliver assessment](../../docs/work-assessments.md). The controller checks referenced file hashes; it cannot observe unreported attempts or prove the diagnosis. Include shared documentation paths in scope only when those edits are authorized; run-local storage preserves history without broadening source scope. Existing runs keep their captured selection.
|
|
34
|
+
|
|
35
|
+
## Done when
|
|
36
|
+
|
|
37
|
+
- Look up: the signature was searched and the result (match or none) stated before diagnosing.
|
|
38
|
+
- Record: the entry has a signature, the area, every attempt with its result, and a status. Resolved entries name the root cause, fix commit, and regression test.
|
|
39
|
+
|
|
40
|
+
## Anti-patterns
|
|
41
|
+
|
|
42
|
+
| Name | The tell | Fix |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| Diagnose first, check later | Debugging before searching the ledger | Search first; it takes seconds |
|
|
45
|
+
| Success-only record | Only the working fix is logged | Log every failed attempt and why |
|
|
46
|
+
| Raw paste | A 200-line stack trace as the entry | Keep the signature and the key frames |
|
|
47
|
+
| Symptom as cause | "Root cause: the page crashed" | Name the mechanism that produced it |
|
|
48
|
+
| Retrying a known dead end | Same fix as a failed attempt, no new reason | State what changed, or pick another hypothesis |
|
|
49
|
+
| Leaked data | Customer data, tokens, or hostnames from logs | Redact before recording |
|
|
50
|
+
|
|
51
|
+
## Handoff
|
|
52
|
+
|
|
53
|
+
Look up returns the matching entries (or "none") to [Understand](../cyc-understand/SKILL.md). Record returns the entry ID and status to [Deliver](../cyc-deliver/SKILL.md), which reports it. A regression of a resolved entry is worth a row in the improvements log, because the guard that should have caught it did not.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Error ledger entry format
|
|
2
|
+
|
|
3
|
+
Newest entries go at the top. Each entry has a stable ID (`ERR-` plus a number) so other docs and commits can reference it.
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
# Error ledger
|
|
7
|
+
|
|
8
|
+
Search this file before debugging. Signatures strip IDs, timestamps, and paths.
|
|
9
|
+
|
|
10
|
+
## ERR-012 · resolved · Homework finished flag missing after reload
|
|
11
|
+
|
|
12
|
+
- **Signature:** `TypeError: Cannot read properties of undefined (reading 'finished') @ loadAll`
|
|
13
|
+
- **Area:** src/storage.ts, src/homework/**
|
|
14
|
+
- **First seen:** 2026-09-25 · **Resolved:** 2026-09-25 at a1b2c3d
|
|
15
|
+
- **Symptom:** App crashes on load for users with homework saved before the finished feature.
|
|
16
|
+
- **Reproduce:** `node --test test/storage.test.js --test-name-pattern legacy`
|
|
17
|
+
|
|
18
|
+
**Attempts**
|
|
19
|
+
1. ✗ Added `?.` at the crash site. The crash stopped, but old items showed as finished because `undefined` was treated as truthy downstream. Evidence: the legacy count test stayed red.
|
|
20
|
+
2. ✗ Migrated records on save. Did not help users who load before their first save. Evidence: fresh-load test red.
|
|
21
|
+
3. ✓ Default `finished: false` in `loadAll` for records missing the field. Legacy, fresh, and double-mark tests all green.
|
|
22
|
+
|
|
23
|
+
- **Root cause:** Records saved before the feature have no `finished` key, and `loadAll` passed them through unchanged.
|
|
24
|
+
- **Guard:** `test/storage.test.js` › "loads legacy records without finished"
|
|
25
|
+
- **Related:** context doc homework.md, 2026-09-25 entry
|
|
26
|
+
|
|
27
|
+
## ERR-011 · open · Intermittent 502 on /api/assignments
|
|
28
|
+
|
|
29
|
+
- **Signature:** `502 Bad Gateway /api/assignments` (about 1 in 40 requests)
|
|
30
|
+
- **Area:** server/routes/assignments.ts
|
|
31
|
+
- **First seen:** 2026-09-20
|
|
32
|
+
- **Reproduce:** `for i in $(seq 200); do curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/api/assignments; done | sort | uniq -c`
|
|
33
|
+
|
|
34
|
+
**Attempts**
|
|
35
|
+
1. ✗ Raised the proxy timeout from 30s to 60s. Rate unchanged (5 in 200). Not a timeout.
|
|
36
|
+
|
|
37
|
+
- **Current best hypothesis:** Connection pool exhaustion under the concurrent reminder job. Next check: log pool size during the job window.
|
|
38
|
+
```
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-explore
|
|
3
|
+
description: "Settle an open decision by comparing genuinely different options or building a throwaway prototype, then recommend one. Use when the user asks \"which approach\", \"what are my options\", or \"what should this look like\", when earlier options were rejected, or when a design fork would be expensive to reverse."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Explore to decide
|
|
7
|
+
|
|
8
|
+
Exploration exists to answer a question. **No decision, no prototype.** Follow the [handoff contract](../../docs/skill-contract.md).
|
|
9
|
+
|
|
10
|
+
## The core loop
|
|
11
|
+
|
|
12
|
+
1. **Write the question at the top.** "Should finished homework disappear or move to a collapsed section?" If you cannot write the question, go back to [Frame](../cyc-frame/SKILL.md).
|
|
13
|
+
2. **Classify it: observable or preference?** If building something small would show the answer (performance, feel, whether it fits), build it instead of asking. If it is pure taste or business priority, lay out the options and ask.
|
|
14
|
+
3. **Generate options that differ in kind.** Different journey, data boundary, architecture, or narrative. Two color schemes of the same layout do not count. Three options is usually right.
|
|
15
|
+
4. **Choose the prototype branch.**
|
|
16
|
+
- **Logic question** (state model, algorithm, API shape): a small script or test file that exercises each option with realistic data.
|
|
17
|
+
- **UI question:** mount the variants on the real page behind a simple switch, using realistic content. A real page beats a blank canvas.
|
|
18
|
+
Label every prototype as throwaway and put the question in its first line.
|
|
19
|
+
5. **Compare against the same criteria.** A small table, one row per option, the task's criteria as columns, plus what the prototype showed.
|
|
20
|
+
6. **Recommend one.** Give a clear pick and the reason. The user wants a strong read, not a menu. Leave the choice with them only when it depends on their taste or priorities.
|
|
21
|
+
7. **When all options are rejected, find out why first.** Extract the reason, add it to the frame as a criterion, then generate new options.
|
|
22
|
+
|
|
23
|
+
## Done when
|
|
24
|
+
|
|
25
|
+
- The question is written.
|
|
26
|
+
- Options differ in kind, and each is compared on the same criteria.
|
|
27
|
+
- Any prototype answers the question and is labeled throwaway.
|
|
28
|
+
- There is a recommendation with a reason, or a named taste decision for the user.
|
|
29
|
+
|
|
30
|
+
## Anti-patterns
|
|
31
|
+
|
|
32
|
+
| Name | The tell | Fix |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| Menu without a pick | "Here are three options" and nothing more | Recommend one |
|
|
35
|
+
| Cosmetic variants | Options differ in naming, color, or copy | Vary the structure |
|
|
36
|
+
| Prototype creep | The throwaway is being made production-ready | Stop; hand the decision to Design |
|
|
37
|
+
| Exploring a settled question | Options generated when the user already chose | Respect the decision |
|
|
38
|
+
|
|
39
|
+
## Handoff
|
|
40
|
+
|
|
41
|
+
Pass the recommendation, comparison, and what the prototype could not show (persistence, scale, real data) to the stage returned by `run next`: [Challenge](../cyc-challenge/SKILL.md) in Explore, [Verify](../cyc-verify/SKILL.md) in Evaluate, or [Build](../cyc-build/SKILL.md) in Experience. A recommendation does not authorize implementation on an advisory route. Quarantine throwaway prototypes; remove only artifacts created for this exploration, preserving user work.
|