@erclx/canon 5.63.0 → 5.65.0

package/governance/ledger/skills/code-craft/SKILL.md

@@ -0,0 +1,53 @@
+---
+title: Code craft skill ledger
+description: Sources for claude/skills/code-craft/SKILL.md, one row per bullet in its concern groups
+---
+
+# Code craft skill ledger
+
+The field is software design at writing time. Parnas, Ousterhout, Fowler, and the Pragmatic Programmer authors carry decomposition and duplication, Refactoring Guru carries the smells, and Birgitta Böckeler's two articles record how agents fail. The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+Parnas's paper refused a read at its ACM DOI, `10.1145/361598.361623`, so the rows quote an open copy of the same paper.
+
+## Name the next change first
+
+| Bullet                             | Source                                                                                                                                                                                                                                                               | Read       |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Name the likely next change first  | [Parnas, On the Criteria To Be Used in Decomposing Systems into Modules](https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria_for_modularization.pdf): "one begins with a list of difficult design decisions or design decisions which are likely to change" | 2026-10-24 |
+| The shape touching one place wins  | [Fowler, Reducing Coupling](https://martinfowler.com/ieeeSoftware/coupling.pdf): "If changing one module in a program requires changing another module, then coupling exists."                                                                                       | 2026-10-24 |
+| No named change, the plainest code | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "solve the problem they know needs to be solved now, not the problem that the developer speculates might need to be solved in the future"      | 2026-10-24 |
+
+## Earn depth
+
+| Bullet                             | Source                                                                                                                                                                                                                                                   | Read       |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Inline a pass-through              | [Refactoring Guru, Middle Man](https://refactoring.guru/smells/middle-man): "If a class performs only one action, delegating work to another class, why does it exist at all?"                                                                           | 2026-10-24 |
+| Split by the decision hidden       | [Parnas, On the Criteria](https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria_for_modularization.pdf): "Each module is then designed to hide such a decision from the others", so modules "will not correspond to steps in the processing"      | 2026-10-24 |
+| One decision in one unit           | [Refactoring Guru, Shotgun Surgery](https://refactoring.guru/smells/shotgun-surgery): "Making any modifications requires that you make many small changes to many different classes."                                                                    | 2026-10-24 |
+| One longer function over tiny ones | [Ousterhout and Martin, A Philosophy of Software Design vs Clean Code](https://github.com/johnousterhout/aposd-vs-clean-code): readers "have to flip back and forth between the methods, effectively reconstructing a monolithic version in their minds" | 2026-10-24 |
+
+## Weigh the tensions
+
+| Bullet                                   | Source                                                                                                                                                                                                                                                              | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One piece of knowledge, one place        | [Hunt and Thomas, Orthogonality and the DRY Principle](https://www.artima.com/articles/orthogonality-and-the-dry-principle): "Most people take DRY to mean you shouldn't duplicate code. That's not its intention."                                                 | 2026-10-24 |
+| Only what is asked, seams allowed        | [Fowler, Yagni](https://martinfowler.com/bliki/Yagni.html): Yagni "only applies to capabilities built into the software to support a presumptive feature, it does not apply to effort to make the software easier to modify"                                        | 2026-10-24 |
+| One reason to change, not too many parts | [Ousterhout and Martin, A Philosophy of Software Design vs Clean Code](https://github.com/johnousterhout/aposd-vs-clean-code): two methods are entangled "if, in order to understand how one of them works internally, you also need to read the code of the other" | 2026-10-24 |
+
+## Pass hidden inputs in
+
+| Bullet                                    | Source                                                                                                                                                                                                                                                                  | Read       |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Clock, environment, and globals passed in | [Fowler, Inversion of Control Containers and the Dependency Injection pattern](https://martinfowler.com/articles/injection.html): "to do testing, you need to easily replace real service implementations with stubs or mocks"                                          | 2026-10-24 |
+| Rules free of transport and storage       | [Cockburn, Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/): an application "developed and tested in isolation from its eventual run-time devices and databases"                                                                           | 2026-10-24 |
+| No ports and adapters for record CRUD     | [Microsoft, Design a DDD-oriented microservice](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/ddd-oriented-microservice): "Simpler responsibilities, like a CRUD service, can be managed with simpler approaches." | 2026-10-24 |
+
+## Check your own diff
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                        | Read       |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A copy where a change belonged          | [Böckeler, The role of developer skills in agentic coding](https://martinfowler.com/articles/exploring-gen-ai/13-role-of-developer-skills.html): "Not realising that a UI component is already implemented elsewhere, and therefore creating duplicate code"  | 2026-10-24 |
+| One responsibility across files         | [Refactoring Guru, Shotgun Surgery](https://refactoring.guru/smells/shotgun-surgery): "A single responsibility has been split up among a large number of classes."                                                                                            | 2026-10-24 |
+| A feature nobody asked for              | [Böckeler, How far can we push AI autonomy in code generation?](https://martinfowler.com/articles/pushing-ai-autonomy.html): "We frequently got additional endpoints and features that we did not ask for in the requirements."                               | 2026-10-24 |
+| An assumption where a question belonged | [Böckeler, How far can we push AI autonomy in code generation?](https://martinfowler.com/articles/pushing-ai-autonomy.html): "Gaps in the requirements will be filled with assumptions", as when a priority field "was assumed by AI to have the value set"   | 2026-10-24 |
+| A brute-force fix                       | [Böckeler, The role of developer skills in agentic coding](https://martinfowler.com/articles/exploring-gen-ai/13-role-of-developer-skills.html): "AI sometimes took brute-force approaches to solve issues rather than diagnosing what actually caused them." | 2026-10-24 |

package/governance/ledger/skills/codebase-layout/SKILL.md

@@ -0,0 +1,64 @@
+---
+title: Codebase layout skill ledger
+description: Sources for claude/skills/codebase-layout/SKILL.md, one row per bullet in its concern groups
+---
+
+# Codebase layout skill ledger
+
+The field is source organization. Robert Martin carries cohesion and folder naming, Kent C. Dodds and Robin Wieruch carry colocation and promotion, bulletproof-react carries the import direction, and the Go blog carries file and package naming. The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+No outside source takes a side on when a plan states a path, so the rows for stating a reason, naming a new folder, and reading a reference are house choices naming the misplacement each prevents.
+
+## Read the project's strategy first
+
+| Bullet                                | Source                                                                                                                                                                                                          | Read       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Name the project's layout first       | [React, File Structure](https://legacy.reactjs.org/docs/faq-structure.html): "React doesn’t have opinions on how you put files into folders", so the project's own layout is the only one a new file can follow | 2026-10-24 |
+| Keep to that strategy                 | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "choose a strategy that works for you and your team and be consistent across the project"                          | 2026-10-24 |
+| A strategy change is its own decision | House choice: a strategy changed as a side effect of placing one file leaves two strategies in the tree, and every later reader guesses which one a file follows                                                | 2026-10-24 |
+
+## Group what changes together
+
+| Bullet                              | Source                                                                                                                                                                                                                                                     | Read       |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One folder per reason to change     | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Gather together the things that change for the same reasons. Separate those things that change for different reasons." | 2026-10-24 |
+| Name a folder for what it holds     | [Martin, Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html): "Your architectures should tell readers about the system, not about the frameworks you used in your system."                               | 2026-10-24 |
+| No bare `utils` or `helpers` bucket | [Gerrand, Package names](https://go.dev/blog/package-names): "Packages named util , common , or misc provide clients with no sense of what the package contains."                                                                                          | 2026-10-24 |
+
+## Name a file for what it covers inside its folder
+
+| Bullet                                 | Source                                                                                                                                                                                                                    | Read       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The stem never repeats the folder      | [Gerrand, Package names](https://go.dev/blog/package-names): "Since client code uses the package name as a prefix when referring to the package contents, the names for those contents need not repeat the package name." | 2026-10-24 |
+| Drop the prefix and retarget on a move | House choice: a file moved into a subfolder that keeps its old prefix says its folder twice, and a citation left on the old path resolves nowhere                                                                         | 2026-10-24 |
+| The stem runs to the first dot         | House choice: reading the stem past a suffix lets `checkout/checkout.test.ts` pass a check that `checkout/checkout.md` fails, though both repeat their folder                                                             | 2026-10-24 |
+
+## Split before the file lands
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                     | Read       |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Split on a second role, before landing | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Separate those things that change for different reasons." Splitting before the file lands is a House choice: the split costs a handful of paths then and 98 later, as the body records | 2026-10-24 |
+| Ten files is a prompt, not a gate      | House choice: no source gives a reliable ceiling, and a count fails a large folder of one role that reads fine flat while passing a small one mixing two                                                                                                                                                                   | 2026-10-24 |
+| A new role gets a named folder         | House choice: a role whose first file lands beside its nearest neighbor leaves the folder holding two roles, and the next file copies the first                                                                                                                                                                            | 2026-10-24 |
+
+## Place a file with its consumer
+
+| Bullet                         | Source                                                                                                                                                                                                                                             | Read       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Colocate with the one consumer | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): "Place code as close to where it's relevant as possible"                                                                                                                              | 2026-10-24 |
+| Promote on the second consumer | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "if exactly one feature uses a util, it lives inside that feature", and "once two or more features need it, it moves up to the shared layer"               | 2026-10-24 |
+| Imports flow one way           | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "the code should flow in one direction, from shared parts of the code to the application (shared -> features -> app)" | 2026-10-24 |
+
+## State the reason on every new path
+
+| Bullet                                | Source                                                                                                                                                                | Read       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A one-clause reason per new path      | House choice: a worker copies the path a plan gives it, so a path with no stated reason lands beside its nearest neighbor and the plan's placement call is never made | 2026-10-24 |
+| Name a new folder where it is created | House choice: a folder the plan leaves implied is inferred by the worker, who drops the file in the nearest existing folder instead                                   | 2026-10-24 |
+
+## Read the reference for the category
+
+| Bullet                     | Source                                                                                                                                                                        | Read       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Interface source reference | House choice: an interface file placed without `frontend.md` lands in the shared `components/` or `lib/` folder whatever its consumer, the flat growth that reference records | 2026-10-24 |
+| Test file reference        | House choice: a test helper placed without `tests.md` lands beside the specs it serves, so the end to end folder stops holding one role                                       | 2026-10-24 |

package/governance/ledger/skills/codebase-layout/frontend.md

@@ -0,0 +1,62 @@
+---
+title: Frontend layout reference ledger
+description: Sources for claude/skills/codebase-layout/references/frontend.md, one row per bullet
+---
+
+# Frontend layout reference ledger
+
+The field is interface source organization. bulletproof-react carries feature folders and the import direction, Robin Wieruch carries the levels and the promotion rule, and the Next.js docs carry routing. Each row cites the bullet's own inline link where the reference carries one.
+
+The worked failure reports what one project's folders did, so its rows are house choices naming the failure the incident shows rather than outside citations.
+
+## Feature folders against shared UI
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                  | Read       |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One feature's code under its folder     | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "organize most of the code within the features folder", and "Only include the ones that are necessary for the feature."    | 2026-10-24 |
+| Shared `components/` for two features   | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): `components` holds "shared components used across the entire application"                                                  | 2026-10-24 |
+| One feature's component is feature code | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): feature components "are often only used once in a React project", while generic UI components "are used by more than one component"                             | 2026-10-24 |
+| No feature imports another              | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "It might not be a good idea to import across the features. Instead, compose different features at the application level." | 2026-10-24 |
+| Enforce the flow with an import lint    | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "To forbid cross-feature imports, you can use ESLint", through `import/no-restricted-paths`                                | 2026-10-24 |
+
+## Grow in levels
+
+| Bullet                          | Source                                                                                                                                                                                                                                                    | Read       |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Start flat                      | [React, File Structure](https://legacy.reactjs.org/docs/faq-structure.html): "If you feel completely stuck, start by keeping all files in a single folder. Eventually it will grow large enough that you will want to separate some files from the rest." | 2026-10-24 |
+| The next level on a named event | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "The day the customer feature needs it too, it moves up to the top-level hooks/ folder."                                                                          | 2026-10-24 |
+| One level per change            | House choice: a plan that jumps from flat to a full feature tree rewrites every import in the project in one diff no review can follow                                                                                                                    | 2026-10-24 |
+
+## Routes
+
+| Bullet                                    | Source                                                                                                                                                                                                                                      | Read       |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The router's own conventions first        | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): the page gives "an overview of all the folder and file conventions in Next.js, and recommendations for organizing your project"                | 2026-10-24 |
+| An unopinionated framework leaves it open | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "Next.js is unopinionated about how you organize and colocate your project files."                                                             | 2026-10-24 |
+| One strategy, kept consistent             | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "choose a strategy that works for you and your team and be consistent across the project"                                                      | 2026-10-24 |
+| A route's component in a private folder   | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): private folders "colocate non-routable files", as `app/blog/_components/Post.tsx` is marked "Not routable" and a "safe place for UI utilities" | 2026-10-24 |
+| `components` and `lib` are placeholders   | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "we're using components and lib folders as generalized placeholders, their naming has no special framework significance"                       | 2026-10-24 |
+
+## Hooks and helpers
+
+| Bullet                                  | Source                                                                                                                                                                                             | Read       |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One feature's hook inside it            | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "A hook that only the project feature uses lives inside features/project/hooks/ ."                         | 2026-10-24 |
+| Promote on the second feature           | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "once two or more features need it, it moves up to the shared layer"                                       | 2026-10-24 |
+| Split a shared `lib/` holding two roles | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Separate those things that change for different reasons."      | 2026-10-24 |
+| A helper named for what it does         | [Gerrand, Package names](https://go.dev/blog/package-names): "Avoid meaningless package names. Packages named util , common , or misc provide clients with no sense of what the package contains." | 2026-10-24 |
+
+## Fixtures and sample data
+
+| Bullet                            | Source                                                                                                                                                      | Read       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Fixtures beside their feature     | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): "Things that change together should be located as close as reasonable."                        | 2026-10-24 |
+| Promote a fixture on two features | House choice: a fixture moved to shared code for one feature's tests drifts from that feature, and the next change to it lands far from the tests it breaks | 2026-10-24 |
+
+## A worked failure
+
+| Bullet                                        | Source                                                                                                                                                               | Read       |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The rules said split, and nobody applied them | House choice: a rule loaded beside a plan that names every file as a sibling of the last loses to the plan, so placement has to be decided where the path is written | 2026-10-24 |
+| The split touched 98 files                    | House choice: a split put off until a folder overflows touches every import of every file in it, and a folder left without a placement rule grows flat again         | 2026-10-24 |
+| A named subfolder at the twelfth file         | House choice: the cost of placement grows with the folder, so the cheapest split is the one a plan names when the second role's first file arrives                   | 2026-10-24 |

package/governance/ledger/skills/codebase-layout/tests.md

@@ -0,0 +1,26 @@
+---
+title: Test layout reference ledger
+description: Sources for claude/skills/codebase-layout/references/tests.md, one row per bullet
+---
+
+# Test layout reference ledger
+
+The field is test file organization. Kent C. Dodds carries colocating a test with its module, and Playwright's fixtures and page object docs carry the split between specs and support. The reference's worked failure is prose rather than bullets, so it takes no table.
+
+## Unit and component tests
+
+| Bullet                                | Source                                                                                                                                                                                                                                      | Read       |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A test beside its module              | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): "we should co-locate our tests files with the file or group of files they are testing"                                                                                         | 2026-10-24 |
+| The test moves with the module        | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): with a mirrored tree, "We'd move or delete a src/ file without updating the corresponding" file beside it, and "All the pitfalls described above apply here as well" for tests | 2026-10-24 |
+| A one-file factory stays in that file | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "if exactly one feature uses a util, it lives inside that feature", and "once two or more features need it, it moves up to the shared layer"        | 2026-10-24 |
+
+## End to end tests
+
+| Bullet                                  | Source                                                                                                                                                                                                                                               | Read       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Only specs in the runner's folder       | House choice: support code among the specs gives a new spec no single place to find its setup, and the next helper lands beside the others                                                                                                           | 2026-10-24 |
+| One merged fixtures module              | [Playwright, Fixtures](https://playwright.dev/docs/test-fixtures): an extended test "can be used in multiple test files, and each of them will get the fixtures", and `mergeTests` combines "test fixtures from multiple files or modules"           | 2026-10-24 |
+| Each page object its own module         | [Playwright, Fixtures](https://playwright.dev/docs/test-fixtures) imports each page object from its own module, as `TodoPage` from `./todo-page`, and [page object models](https://playwright.dev/docs/pom) capture "element selectors in one place" | 2026-10-24 |
+| Support in its own folder, named by use | House choice: a single `helpers` file every spec imports grows into a bucket naming no role, the fault the body's naming rule forbids for any folder                                                                                                 | 2026-10-24 |
+| Group specs by journey once they mix    | House choice: specs for two journeys in one folder hold two roles, so a reader finds a journey's specs only by opening each file                                                                                                                     | 2026-10-24 |

package/governance/ledger/skills/deprecation-migration/SKILL.md

@@ -0,0 +1,68 @@
+---
+title: Deprecation and migration skill ledger
+description: Sources for claude/skills/deprecation-migration/SKILL.md, one row per bullet or ordered step in its concern groups
+---
+
+# Deprecation and migration skill ledger
+
+The field is retiring a surface its callers still reach. Software Engineering at Google carries deprecation policy and the Churn Rule, Martin Fowler carries parallel change and the strangler fig, and Addy Osmani's `agent-skills` carries the bridges and zombie code. The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+## Decide whether to deprecate at all
+
+| Bullet                   | Source                                                                                                                                                                                               | Read       |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| What keeping it costs    | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): "code is a liability, not an asset", with costs "borne as a system is maintained across its lifetime" | 2026-10-24 |
+| Who calls it             | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): tools that "statically determine which customers use a given library"                                 | 2026-10-24 |
+| What replaces it         | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): "deprecation usually isn't an option until a newer system is available"                               | 2026-10-24 |
+| Who migrates the callers | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): "without explicit owners, a deprecation process is unlikely to make meaningful progress"              | 2026-10-24 |
+
+## Choose advisory or compulsory
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                          | Read       |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Start advisory                         | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): "Advisory deprecations are those that don't have a deadline", for a system "the team knows" has "been replaced"                                                                                  | 2026-10-24 |
+| Compulsory once a removal date stands  | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): compulsory deprecation "usually comes with a deadline for removal of the obsolete system"                                                                                                        | 2026-10-24 |
+| Actionable and well-timed warnings     | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): a warning is actionable when "the user can use the warning to actually perform some relevant action", and relevant "if it surfaces at a time when a user actually performs the indicated action" | 2026-10-24 |
+| No open advisory without date or owner | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): advisory deprecation "often lacks enforcement: we hope that clients move, but can't force them to"                                                                                               | 2026-10-24 |
+
+## Migrate the callers yourself
+
+| Bullet                             | Source                                                                                                                                                                                                           | Read       |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Migrate every caller you can reach | [Software Engineering at Google, ch. 1](https://abseil.io/resources/swe-book/html/ch01.html): "infrastructure teams must do the work to move their internal users to new versions themselves", the Churn Rule    | 2026-10-24 |
+| A compatible path for the rest     | [Software Engineering at Google, ch. 1](https://abseil.io/resources/swe-book/html/ch01.html): the Churn Rule's other branch, "or do the update in place, in backward-compatible fashion"                         | 2026-10-24 |
+| No new feature on the old surface  | [Fowler, Strangler Fig](https://martinfowler.com/bliki/StranglerFigApplication.html): the move "begins with small additions, often new features, that are built on top of, yet separate to the legacy code base" | 2026-10-24 |
+
+## Prove zero consumers before removal
+
+| Bullet                        | Source                                                                                                                                                                                                                               | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Imports and direct calls      | [Software Engineering at Google, ch. 15](https://abseil.io/resources/swe-book/html/ch15.html): Code Search and Kythe "statically determine which customers use a given library"                                                      | 2026-10-24 |
+| String references             | House choice: a handler, command, or fixture looked up by name passes an import search and fails at runtime once the surface goes                                                                                                    | 2026-10-24 |
+| Configuration                 | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): removal includes "Remove associated tests, documentation, and configuration"          | 2026-10-24 |
+| Documentation and examples    | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): its zombie signs include "Documentation that references systems that no longer exist" | 2026-10-24 |
+| Copies outside the repository | [Fowler, Parallel Change](https://martinfowler.com/bliki/ParallelChange.html): a change is hardest "on a PublishedInterface with multiple or external clients", for whom migration "will be the longest phase"                       | 2026-10-24 |
+
+## Bridge with an adapter or a strangler
+
+| Bullet                           | Source                                                                                                                                                                                                                                     | Read       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Adapter                          | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): "Create an adapter that translates calls from the old interface to the new implementation." | 2026-10-24 |
+| Strangler                        | [Fowler, Strangler Fig](https://martinfowler.com/bliki/StranglerFigApplication.html): "we move bits of behavior from the legacy system into the new code base", with bridging code "that will go away once the modernization is complete"  | 2026-10-24 |
+| Adapter when the interface stays | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): under an adapter "Consumers keep using the old interface while you migrate the backend"     | 2026-10-24 |
+
+## Expand, migrate, contract as three changes
+
+| Step     | Source                                                                                                                                                                                                    | Read       |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Expand   | [Fowler, Parallel Change](https://martinfowler.com/bliki/ParallelChange.html): "In the expand phase you augment the interface to support both the old and the new versions."                              | 2026-10-24 |
+| Migrate  | [Fowler, Parallel Change](https://martinfowler.com/bliki/ParallelChange.html): "During the migrate phase you update all clients using the old version to the new version. This can be done incrementally" | 2026-10-24 |
+| Contract | [Fowler, Parallel Change](https://martinfowler.com/bliki/ParallelChange.html): "Once all usages have been migrated to the new version, you perform the contract phase to remove the old version"          | 2026-10-24 |
+
+## Treat zombie code as a decision to make
+
+| Bullet                              | Source                                                                                                                                                                                                                                            | Read       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Run the zero-consumers check on it  | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): removal waits until you "Verify zero active usage (metrics, logs, dependency analysis)"            | 2026-10-24 |
+| Remove it when the check is clean   | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): against "Someone might need it later", "If it's needed later, it can be rebuilt."                  | 2026-10-24 |
+| An owner or a deprecation otherwise | [agent-skills, deprecation and migration](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md): "Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan." | 2026-10-24 |

package/governance/ledger/skills/design-taste/SKILL.md

@@ -0,0 +1,64 @@
+---
+title: Design taste skill ledger
+description: Sources for claude/skills/design-taste/SKILL.md, one row per bullet in its concern groups
+---
+
+# Design taste skill ledger
+
+The field is visual design judgment. Jesse James Garrett's planes carry the layer order, the Nielsen Norman Group carries redesign strategy and tone, and Josh Comeau carries shadow lighting. The ten defaults are catalog observations, as in the `tells.md` ledger, recording model output and never cited as an authority. `## What this delegates` routes, so it takes no table.
+
+No outside authority takes a side on the four grey-box rules, three layer rules, the focus ring lock, or the greenfield mode. Each of those nine rows is a house choice naming the failure it prevents.
+
+## The defaults you are reaching past
+
+| Bullet                       | Source                                                                                                                                                                                                                                         | Read       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Three equal cards            | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Three equal card columns as feature row. This is the most generic AI layout."                               | 2026-10-24 |
+| The centered hero            | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Centred headline, subtitle, two buttons, screenshot below"                                                | 2026-10-24 |
+| The violet-to-blue accent    | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Violet / indigo gradients on hero, buttons and glows" are banned, reached past with "flat colour"         | 2026-10-24 |
+| Numbered labels              | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Step 1 / Step 2 / Step 3" is banned, since "The actual step content is the label" | 2026-10-24 |
+| The scroll cue               | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Scroll cues are banned."                                                          | 2026-10-24 |
+| A dot before every item      | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): a dot is "Only acceptable when conveying real semantic state"                      | 2026-10-24 |
+| A glow for elevation         | Catalog observation, [Impeccable craft floor](https://github.com/pbakaus/impeccable/blob/main/skill/reference/craft-floor.md): "shadows carry an offset and a soft blur. A zero-offset colored halo is decoration."                            | 2026-10-24 |
+| A screenshot built of shapes | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "NO div-based fake product UI in the hero"                                         | 2026-10-24 |
+| Placeholder that announces   | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Placeholder company names like "Acme Corp"", replaced with "contextual, believable brand names"             | 2026-10-24 |
+| Warm verbs over meaning      | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Never use "Elevate", "Seamless", "Unleash"", and "Write plain, specific language"                           | 2026-10-24 |
+
+## The layers, and the order they settle
+
+| Bullet                                 | Source                                                                                                                                                                                                                         | Read       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| A higher layer over a broken lower one | [Garrett, The Elements of User Experience, ch. 2](http://www.jjg.net/elements/pdf/elements_ch02.pdf): "the choices available to us on each plane are constrained by the decisions we make about issues on the planes below it" | 2026-10-24 |
+| A lower layer through a finished one   | House choice: a finished palette, type, and imagery hide a weak composition or layout, so the round judges the wrong layer and passes it                                                                                       | 2026-10-24 |
+| A round varies one layer               | House choice: a round varying several layers yields a pick that cannot say which difference decided it, so the next round repeats the question                                                                                 | 2026-10-24 |
+| Never settle a higher layer first      | [Garrett, The Elements of User Experience, ch. 2](http://www.jjg.net/elements/pdf/elements_ch02.pdf): "Each plane is dependent on the planes below it."                                                                        | 2026-10-24 |
+| Real copy before the composition sets  | House choice: a composition settled against stand-in copy breaks once real copy of another length and tone runs through it                                                                                                     | 2026-10-24 |
+| Check the layers below the complaint   | [Garrett, The Elements of User Experience, ch. 2](http://www.jjg.net/elements/pdf/elements_ch02.pdf): "When the choices we make don't align with those above and below, projects often derail"                                 | 2026-10-24 |
+
+## Grey-box when judging layers 1 to 4
+
+| Bullet                         | Source                                                                                                                                         | Read       |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Flat neutral blocks            | House choice: a fill, an accent, or an image left in a grey-box pulls the judgment toward a layer the round is not judging                     | 2026-10-24 |
+| Real text at real length       | House choice: greeked copy hides the wrapping and overflow that real copy at length produces, so a composition passes and then breaks          | 2026-10-24 |
+| FPO at true size               | House choice: an unmarked placeholder region is read as a decided element and ships as one                                                     | 2026-10-24 |
+| Return to the finished surface | House choice: a grey-box handed over as the deliverable reads to the operator as unfinished work rather than as the answer to a layer question | 2026-10-24 |
+
+## Lock what must not vary across a surface
+
+| Bullet                | Source                                                                                                                                                                                                                                           | Read       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| One accent            | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "More than one accent color. Pick one. Remove the rest."                                                       | 2026-10-24 |
+| One radius system     | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "One medium border radius (12–16px) on everything" is reached past with "Square or fully round, chosen once" | 2026-10-24 |
+| One theme             | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "A single dark-background section breaking an otherwise light page looks like a copy-paste accident."          | 2026-10-24 |
+| One copy register     | [NN/g, The Four Dimensions of Tone of Voice](https://www.nngroup.com/articles/tone-of-voice-dimensions/): "Keep your brand personality consistent", the part that backs one register per composition                                             | 2026-10-24 |
+| One light source      | [Comeau, Designing Beautiful Shadows in CSS](https://www.joshwcomeau.com/css/designing-shadows/): "we should decide on a single light source for all elements on the page", and black shadow "also desaturates it quite a bit"                   | 2026-10-24 |
+| One focus ring weight | House choice: a focus ring varying by component reads as several products on one surface. The `ui-craft` skill owns the visibility floor                                                                                                         | 2026-10-24 |
+
+## Working on something that already exists
+
+| Bullet     | Source                                                                                                                                                                      | Read       |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Greenfield | House choice: an existing surface misread as greenfield discards the brand, content, and routes its callers and readers rely on                                             | 2026-10-24 |
+| Preserve   | [NN/g, Radical Redesign or Incremental Change?](https://www.nngroup.com/articles/radical-incremental-redesign/): "Usually Choose Incremental Changes Over a Major Overhaul" | 2026-10-24 |
+| Overhaul   | [NN/g, Radical Redesign or Incremental Change?](https://www.nngroup.com/articles/radical-incremental-redesign/): "Sometimes a Major Overhaul Is Best"                       | 2026-10-24 |

package/governance/ledger/skills/design-taste/craft.md

@@ -0,0 +1,66 @@
+---
+title: Craft reference ledger
+description: Sources for claude/skills/design-taste/references/craft.md, one row per bullet
+---
+
+# Craft reference ledger
+
+The field is typography and visual design. The authorities are Practical Typography and MDN for type, and the Nielsen Norman Group for navigation and error messages.
+
+Most rows here are catalog observations, being what a community prompt skill recorded models drawing unguided. A catalog row records model output and is never cited as an authority.
+
+## Optical against mathematical
+
+| Bullet                              | Source                                                                                                                                                                                                                                                 | Read       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Centering by the numbers            | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments to feel right" | 2026-10-24 |
+| Equal vertical padding bottom-heavy | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Top and bottom padding are always identical", and "bottom padding often needs to be slightly larger"                | 2026-10-24 |
+| Optical size beats declared size    | [Wikipedia, Overshoot](https://en.wikipedia.org/wiki/Overshoot_%28typography%29): round letters overshoot "to achieve an optical effect of being the same size"                                                                                        | 2026-10-24 |
+| Hang the opening mark               | [hanging-punctuation](https://developer.mozilla.org/en-US/docs/Web/CSS/hanging-punctuation): "An opening bracket or quote at the start of the first formatted line" hangs                                                                              | 2026-10-24 |
+
+## Alignment across siblings
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                | Read       |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Shared elements align in a row | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "align shared elements (titles, descriptions, prices, buttons) across all items. Misaligned baselines make the layout look broken." | 2026-10-24 |
+| Pin actions to the bottom      | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Pin buttons to the bottom of each card so they form a clean horizontal line regardless of content above"                           | 2026-10-24 |
+| Feature lists start level      | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "the list of features should start at the same Y position across all columns", with "fixed-height title/price blocks"               | 2026-10-24 |
+| Forced equal height is wrong   | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Cards of equal height forced by flexbox. Allow variable heights or use masonry when content varies in length."                     | 2026-10-24 |
+
+## Hierarchy without scale
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                          | Read       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Weights between regular, bold   | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Only Regular (400) and Bold (700) weights used. Introduce Medium (500) and SemiBold (600) for more subtle hierarchy."                                        | 2026-10-24 |
+| Color, space, position carry    | [Practical Typography, Headings](https://practicaltypography.com/headings.html) backs the space half: "The best way to emphasize a heading is by putting space above and below". Color and position are a House choice: a level carried by size alone runs out of steps a reader can tell apart | 2026-10-24 |
+| An enormous heading is shouting | [Practical Typography, Headings](https://practicaltypography.com/headings.html): "It's fine to make the point size bigger, but just a little."                                                                                                                                                  | 2026-10-24 |
+
+## Type detail
+
+| Bullet             | Source                                                                                                                                                                                                                                                | Read       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Orphans            | [text-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/text-wrap): `balance` suits "a short number of lines, such as headings, captions, and blockquotes"                                                                                       | 2026-10-24 |
+| Measure            | [Practical Typography, Line length](https://practicaltypography.com/line-length.html): "Aim for an average line length of 45–90 characters, including spaces."                                                                                        | 2026-10-24 |
+| Figures in columns | [font-variant-numeric](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric): `tabular-nums` sets figures "the same size, allowing them to be easily aligned"                                                                        | 2026-10-24 |
+| Tracking by size   | [Practical Typography, Letterspacing](https://practicaltypography.com/letterspacing.html): "always add 5–12% extra letterspacing to text in all caps or small caps", and typographers "remove letterspacing from lowercase text used at larger sizes" | 2026-10-24 |
+| Casing             | [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style): "Always use sentence case, even in page titles and service names", the source the `ui-craft` copy ledger records for the rule this bullet points at         | 2026-10-24 |
+
+## Depth and texture
+
+| Bullet                         | Source                                                                                                                                                                                                                        | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Tint the shadow                | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Tint shadows to match the background hue", rather than "pure black at low opacity"         | 2026-10-24 |
+| Zero texture reads sterile     | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Flat design with zero texture. Add subtle noise, grain, or micro-patterns to backgrounds." | 2026-10-24 |
+| The even linear gradient       | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Perfectly even gradients", in place of "standard linear 45-degree fades"                   | 2026-10-24 |
+| Let something cross a boundary | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "No overlap or depth. Elements sit flat next to each other."                                | 2026-10-24 |
+
+## Small things that read as unfinished
+
+| Bullet                       | Source                                                                                                                                                                                                                                                                                                                      | Read       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A link that goes nowhere     | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Dead links. Buttons that link to `#`."                                                                                                                                                   | 2026-10-24 |
+| No current location          | [NN/g, Navigation: You Are Here](https://www.nngroup.com/articles/navigation-you-are-here/): "Navigation should not only show where you can go but also where you are now."                                                                                                                                                 | 2026-10-24 |
+| One portrait for many people | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Same avatar image for multiple users. Use unique assets for every distinct person."                                                                                                      | 2026-10-24 |
+| Every item dated alike       | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "All blog post dates identical"                                                                                                                                                           | 2026-10-24 |
+| An exclamation in success    | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Exclamation marks in success messages. Remove them. Be confident, not loud."                                                                                                             | 2026-10-24 |
+| An error opening on sorry    | [NN/g, Error-message guidelines](https://www.nngroup.com/articles/error-message-guidelines/) backs the fix half: "offer some potential remedies". The no-apology half is a catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "Errors don't apologize" | 2026-10-24 |

package/governance/ledger/skills/design-taste/kinds.md

@@ -0,0 +1,58 @@
+---
+title: Rules by kind ledger
+description: Sources for claude/skills/design-taste/references/kinds.md, one row per bullet
+---
+
+# Rules by kind ledger
+
+The field is interface design by surface kind. The authorities are Practical Typography for reading and the Nielsen Norman Group for wayfinding and command shortcuts.
+
+Impeccable's three mode references sort a surface by what the visitor came to do, and most rows below restate them. Impeccable is a community prompt skill rather than an authority, so each such row is a catalog observation. A House choice row names the failure a routing or contrast bullet prevents.
+
+## Marketing and promotional
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                          | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Optimizes for comprehension    | Catalog observation, [Impeccable persuade mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-persuade.md): "the opening must make the offer intelligible and desirable, expose a clear action"                                                          | 2026-10-24 |
+| Composition carries the weight | House choice: a palette round run against a flat composition changes nothing a stranger notices, since section order is what they judge first                                                                                                                                   | 2026-10-24 |
+| Vary the section shape         | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Every section the same layout family" is a structural tell, reached past with "Different composition per section"                          | 2026-10-24 |
+| Low density                    | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Dense layouts work for data dashboards, not for marketing pages."                                                                            | 2026-10-24 |
+| Every claim names a real thing | Catalog observation, [Impeccable persuade mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-persuade.md): the opening must "demonstrate something only this product can prove"                                                                         | 2026-10-24 |
+| Motion permitted and rationed  | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "Use non-user-triggered motion sparingly and deliberately, only to draw attention", since one orchestrated moment "lands better than scattered effects" | 2026-10-24 |
+| Product rules wrong here       | House choice: tables, persistent chrome, and state indicators ask a stranger to read state they hold none of, so a marketing page reads as a product screen                                                                                                                     | 2026-10-24 |
+
+## Application and product UI
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                              | Read       |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Optimizes for throughput        | Catalog observation, [Impeccable operate mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-operate.md): "On an Operate surface the visitor came to get a job done"                                                                                                         | 2026-10-24 |
+| High density is correct         | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Dense layouts work for data dashboards"                                                                                                                          | 2026-10-24 |
+| The states carry the weight     | Catalog observation, [Impeccable operate mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-operate.md): the first viewport names "the data the visitor reads first and its states"                                                                                         | 2026-10-24 |
+| Whether each state exists       | House choice: the coverage question asked in two skills drifts into two answers, so `ui-craft` holds it and this bullet routes there                                                                                                                                                                | 2026-10-24 |
+| An agentic surface's states     | House choice: a spinner over long agent work hides whether the work is reading, waiting on the person, or done, which is the one thing the reader came to learn                                                                                                                                     | 2026-10-24 |
+| Chrome persistent and quiet     | Catalog observation, [Impeccable operate mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-operate.md): "Someone who uses tools like this one should know where everything is before they notice the world."                                                               | 2026-10-24 |
+| Motion is feedback              | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "Motion that answers a person's action (opening, expanding, confirming) is welcome when it shows what changed."                                                             | 2026-10-24 |
+| The direction lends four things | Catalog observation, [Impeccable operate mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-operate.md): "The world lends four things and only these: type, palette, density, and one signature move. It never supplies the layout, the navigation model, or the controls." | 2026-10-24 |
+| A borrowed interface lends four | Catalog observation, [Impeccable operate mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-operate.md): a world taken from a terminal or instrument "comes back as a costume of that tool on a working screen"                                                             | 2026-10-24 |
+| Check against the category      | Catalog observation, [Impeccable operate mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-operate.md): "with the name covered, does it read as a product of its category, could the visitor do the task from it"                                                          | 2026-10-24 |
+| A command shows its shortcut    | [NN/g, UI copy](https://www.nngroup.com/articles/ui-copy/): shortcuts sit "to the far right of the menu" and "alongside the command text in tool tips"                                                                                                                                              | 2026-10-24 |
+| Marketing rules wrong here      | House choice: generous whitespace and entrance motion cost an operator a scroll or a wait on every glance, on a screen they read constantly                                                                                                                                                         | 2026-10-24 |
+
+## Content and long-form
+
+| Bullet                        | Source                                                                                                                                                                                                                                                  | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Optimizes for reading         | Catalog observation, [Impeccable read mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-read.md): "On a Read surface the visitor came to understand something", judged by "how fast a reader finds and understands the answer" | 2026-10-24 |
+| Measure is capped             | [Practical Typography, Line length](https://practicaltypography.com/line-length.html): "Aim for an average line length of 45–90 characters, including spaces."                                                                                          | 2026-10-24 |
+| Hierarchy from weight, space  | [Practical Typography, Headings](https://practicaltypography.com/headings.html): "The best way to emphasize a heading is by putting space above and below", and "Use bold, not italic."                                                                 | 2026-10-24 |
+| Navigation is a map           | [NN/g, Navigation: You Are Here](https://www.nngroup.com/articles/navigation-you-are-here/): "Navigation should not only show where you can go but also where you are now."                                                                             | 2026-10-24 |
+| Code, tables, figures         | Catalog observation, [Impeccable read mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-read.md): "Code, tables, notes, and figures sit in the standard forms readers already know"                                            | 2026-10-24 |
+| Motion is almost always wrong | Catalog observation, [Impeccable read mode](https://github.com/pbakaus/impeccable/blob/main/skill/reference/mode-read.md): the reading column stays calm, with "nothing performing behind the text"                                                     | 2026-10-24 |
+| Other kinds' rules wrong here | House choice: application density makes long prose tiring to read, and marketing whitespace between paragraphs breaks one argument into unrelated pieces                                                                                                | 2026-10-24 |
+
+## Kinds this file does not cover
+
+| Bullet                 | Source                                                                                                                                                                 | Read       |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Transactional flows    | House choice: a checkout or settings flow given its own section here would restate state coverage and error recovery, which `ui-craft` holds and would drift from here | 2026-10-24 |
+| Terminal and text-mode | House choice: a terminal has no layout engine and its own color rules, so a web rule borrowed for it is wrong in every case this file could state                      | 2026-10-24 |