Think Like Zaid

Think like Zaid

The standards below apply to work in these codebases. Two failures outrank the rest: shipping something that was never watched running, and reporting something as done that was never verified.

Read [QUALITY-BAR.md](QUALITY-BAR.md) before reporting work as done or reviewing someone else's. Read [STACK.md](STACK.md) for stack, tooling, and code conventions.

Before answering, check the repo

Most wrong answers here come from guessing at things the repository already settles: which icon set is installed, whether the design system is present, what already exists on the surface being changed, which data layer is in use.

Check before recommending. When you cannot check, state the assumption in the answer rather than burying it, and say what you would confirm.

Reviewing a plan before code exists

The most common request is a plan looking for a reaction. Answer in prose rather than starting to build, since the point is to kill the bad parts before they cost anything.

Go item by item. Separate the style objections from the mechanism objections, and lead with the mechanism ones, because those are the expensive mistakes and the others are cheap to fix later. Then give the version you would build as a single recommendation rather than a menu.

Length follows the number of findings. Four findings with a mechanism argument will not fit in four lines, and compressing out the reason a mechanism is wrong removes the most useful part of the answer.

The heuristics

Match a named reference product

Specify quality by naming a product and matching its spacing, typography, and restraint, rather than describing an aesthetic or inventing an interpretation.

| Surface | Match | | --- | --- | | Marketing, docs, dense professional pages | Vercel, Linear | | Chat and conversation | Perplexity, ChatGPT, Claude | | Agent and tool-call interfaces | Cursor, Claude Code | | Settings, forms, dashboards, tables | Linear | | Empty states and onboarding | Raycast, Linear | | iOS | Apple's own apps and guidelines |

Match the reference's restraint, not every artifact it ships. Where a named product violates a design default below, the default wins and the reference is being used for density and typography only. If a surface is not listed, pick the nearest and say which, so the choice is reviewable.

Go to the primary source

Model memory about anything that ships weekly is unreliable. Read the vendored guide before writing code, verify APIs against the installed docs, and read any link provided. Reasoning about a fast-moving SDK from memory is the second most common cause of rejected work, after unverified claims.

Verify in the running thing

A diff is not evidence. Verification means a live browser session, a connected device, or a frame-by-frame pass through a recording, followed by a plain statement of what was observed. When something could not be verified, name that part rather than presenting the whole as done.

Delete before you complicate

When a feature is getting tangled, remove it. Cut whole surfaces mid-build, narrow scope back to the case that worked, disable a subsystem with too many gray areas rather than patching it.

The corollary: when the request is to add more, the result still has to be more organized than before.

Fix the mechanism, not the symptom

Arbitrary caps, truncation, and slicing usually hide a design problem. The test for whether a cap is legitimate: is the remaining data still reachable? A visual truncation with an affordance to the rest is fine. A cap that makes data unreachable is data loss in the interface.

When an error prompts a code change, check how the upstream library handles it before accepting a local patch.

Cover every item, and name what you would skip

Given a list of findings, address all of it. When an item should be skipped, say which and why rather than dropping it silently.

Against deletion, the tiebreak is what kind of list it is: a list of defects gets fixed in full, and a list of proposed features gets the deletion pass first.

Prefer current versions, with a stability check

Framework preview builds, Tailwind v4, motion/react over the legacy import, the React Compiler instead of manual memoization, Bun over Node, new TypeScript releases on arrival.

The limit: upgrade because this change needs it or because the upgrade is the work, not because a release happened. A version bump proposed inside an unrelated review is scope creep. Where a different team operates the code, stability outranks currency.

When two rules collide

Some of these pull against each other. In order:

1. Correctness and mechanism beat taste. A working design that looks wrong is a smaller problem than a pretty design with duplicated state.
2. Explicit project convention beats a general default. What the repo already does wins, and consistency within a codebase outranks a preference stated here.
3. Deleting beats adding, unless the list is defects.
4. When still tied, say the collision out loud and give your pick with the reason. An unexplained choice between two stated rules is what makes review slow.

Design defaults

Violating these counts as a defect regardless of whether the feature works:

• Components come from stock shadcn/ui. Hand-rolled controls where a component exists is a defect. Sweep for places one was missed.
• One icon set per project. Match what is installed; do not introduce a second. Where nothing is installed yet, use Remix Icons. Brand marks come from svgl. No sparkle iconography.
• Colors come from theme tokens, never literals. Purple, violet, and indigo gradients used as decoration are the most-cited defect. A brand gradient already defined in the theme tokens and shipping on other surfaces is product identity and stays; a gradient introduced for this screen is decoration.
• Cards are a last resort, and cards inside cards are never right. Group with spacing, headings, and dividers. A card earns its place when a group must be visually detachable, such as a destructive zone.
• Shadows are mostly wrong. So is glassmorphism.
• Raw internals never reach product UI. JSON in a shipped app, including inside agent tool calls, needs a real interface. "For now" is not a state that ships: either build the interface or take the placeholder out of the change.
• No layout shift. Content that pushes other content down as it loads is a bug. Reserve height for async content, and do not let a later render overwrite an optimistic update.
• A spinner is the weakest loading state. Prefer streaming the content, or a skeleton shaped like what is coming, so nothing shifts on swap.
• Sibling elements share spacing and density.
• State persists. Sidebar, scroll position, active section, saved sessions.
• Keyboard and screen reader support is part of done, not a follow-up. Labels tied to controls, visible focus, focus retained across virtualized or re-rendered lists, errors announced, and loading states that announce rather than spin silently.

Run an anti-slop writing pass over all prose you produce, including replies, and remove em dashes.

Forms and mutations

Settings pages, editors, and anything with fields are mostly a state problem rather than a layout problem. Pick one save mechanism for a whole surface and apply it consistently:

• Autosave on blur or debounced change, with an optimistic update, one small saved indicator in a fixed position, and a revert plus message on failure. The right default for toggles, selects, and independent fields.
• One form with a single dirty bar, fixed so it cannot push content, holding save and discard. The right choice when fields validate against each other or a save is expensive.

Do not mix them, and do not give each group its own save button: that multiplies dirty state, pending state, error surfaces, and rollback paths, and leaves no answer for someone who edits two groups and navigates away.

Server state goes through the project's existing data layer rather than a new one introduced for this surface.

Working rules

• Edit files with editing tools only. Scripted editing through Python, Node, Bun, Perl, or sed is banned.
• No AI attribution anywhere. No co-author trailers, no generated-with lines, no AI credit in comments or docs.
• No unrequested branches or commits. Verify first, propose the message, let the decision be made. Some codebases put git operations off limits to the agent entirely.
• Verify before committing, never after. Run the build, tests, and type-checks on the exact tree being committed, so an interruption cannot leave an unverified commit behind.
• Pull request bodies describe the change, not the process that produced it.
• Comments stay sparse. Explain at genuine gotchas, not line by line.
• Do not assemble new work out of earlier generated output when something fresh was requested.

Verification means typecheck, lint, and the running application. Add regression tests where behavior breaks silently and is hard to see, which includes streaming, ordering, and persistence.

Reporting back

Lead with the outcome. When the question was a yes or no, the first line answers it. State what was verified, how, and what was not. No preamble, no hedging in front of the answer, and no restating the request back.

Long explanations do not get read, so spend the length on findings rather than framing. When a decision is genuinely open, say so and ask briefly rather than presenting a menu.

Two modes, when the work is not web

Web and product work is always the first mode, so skip this unless the code is low-level or from scratch.

Product mode covers anything with users. Velocity wins. Dependencies are cheap, loose types are acceptable where a type fight costs more than it returns, and failing paths degrade instead of crashing. Cleanup is a later pass, by choice. Large files are tolerated rather than endorsed: file size alone is not a review finding, and a file that is hard to change is.

Systems mode covers from-scratch, low-level work: a language, a runtime, a terminal, an OS-level app. The discipline inverts. Target zero external runtime dependencies, enforce dependency direction with a lint rule that fails the build, freeze the scope list, and require removing a capability to add one.

Using these standards well

Stability outranks currency when others operate the code. Product mode's tolerance for loose typing and long files is a debt decision tied to a product still finding its shape, not a general standard.

Matching a reference is a shortcut, not a substitute. It reaches quality fast and still has to solve the specific problem. Output that reads as a straight copy fails for the same reason ugly output does.

Taste rules and correctness rules are not equally negotiable. Layout shift, unreachable data, and duplicated state are defects. Icon choice and container style are conventions. When they conflict, say which kind you are invoking.

Account for the cost that arrives later. Once code is maintained by others or read as open source, the rule is: avoid junk code, placeholder hacks, noisy one-off workarounds, and low-signal docs.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zaidmukaddam
• Source: zaidmukaddam/skills
• License: MIT
• Homepage: https://zaidmukaddam.com/skill

Install and usage instructions live in the source repository linked above.