1## Code Quality
2
3Prefer fewer moving parts. Do not introduce a helper, field, abstraction, or
4type unless it removes real duplication or encodes a meaningful invariant.
5Inline a one-caller helper unless it makes a tricky operation substantially
6safer; wrappers around another object's property, trivial context builders, and
7"just in case" extension points are low aura.
8
9Hunt dead code and fake state while editing. A value derived from another source
10should be derived, not stored. A field written only to appease a type and never
11read gets nuked. A cast must constrain real runtime behavior; one that survives
12is localized and justified by an actual API boundary.
13
14Before calling a change done, do a cleanup pass: fewer names, branches, casts,
15public API promises. Ship the smaller locked-in version. Thinking, running, and
16verifying longer to land a correct answer is expected -- "should work" is a
17hypothesis, and say so.
18
19### Comments
20
21Default to no comment; names, types, and structure carry the meaning. One earns
22its place only for a non-obvious "why", an invariant invisible from the local
23code, or a gotcha that will mislead the next reader -- never to restate the code
24or narrate mechanism a reader can follow line by line.
25
26Keep an earned comment to a line, timeless, and rarely first person (no `I`,
27`we`). Prefer documentation comments on declarations. History, deployment
28topology, and cross-file mechanism belong in the commit or the linked issue. Cut
29every clause a competent reader would already infer.
30
31## Output Preferences
32
33Write for an engineer who already knows the mechanism. A figure (pseudocode,
34component tree, ascii diagram) beats the paragraph that would have described it,
35and stands alone -- no sentence after it re-describing what it shows.
36
37**Bold** and _italic_ each render as their own color; use either freely for
38emphasis. _**Bold italic**_ renders red and means warning: a consequence I will
39regret missing, never mere emphasis. Usually zero per message, never two.
40
41- At most one paragraph, plus a figure where one earns its place. A second
42 paragraph means the first did not pick the load-bearing point: choose again,
43 do not append. Six lines is the ceiling; three dense lines beat six padded.
44- Answer the question without expanding the topic. Follow-up questions that
45 imply an expected property (“only behind the flag, right?”) are instructions
46 to verify it and fix any mismatch within the current task's scope, unless I
47 explicitly request read-only analysis. Do not stop at reporting “no.” Withhold
48 unrelated detail; depth is a follow-up I will ask for.
49- These are limits on the report, never on the work. Investigate exhaustively,
50 then say the smallest true thing.
51- Cut every word whose deletion leaves the meaning intact: no hedges
52 ("essentially", "worth noting"), no scaffolding ("that said", "importantly",
53 "in practice"), no restating my question. Open on the payload.
54- Before a tool call: one line, or nothing. After launching a sub-agent:
55 nothing, the transcript already shows what started.
56- No sentence whose subject is you or your process -- no "I looked", "my pass",
57 "let me".
58- A problem you found and fixed goes last, in one line, unemphasized. Same for
59 anything a reviewer or sub-agent caught.
60- Never list undone work or name "the gaps". That is a question for me, or it
61 should have been part of the task.
62- A clause after "rather than" or ", not" must name a real alternative you
63 considered. One per message; pure negation earns no second clause.
64- You cannot judge visual taste. Ship a screenshot or GIF and let me.
65
66## Jujutsu
67
68- My repos use Jujutsu and usually don't have a visible `.git` folder. Never run
69 `git`, and be cautious about jujutsu commands. Here are the standard commands.
70 By default, don't use any other mutating commands.
71 - `jj st` - show current commit + files changed + conflicts + immediate parent
72 - `jj log -r @ -T description --no-graph` show the description for the current
73 commit, which is important for review. consider running
74 `jj st && jj log -r ...` to get both views in a single command.
75 - `jj diff --git`: diff current commit, can take a file/fileset.
76 - `jj file show <path> -r <revision>` - read a file at a revision, such as
77 `main` or previous commit `@-` or change ID.
78 - `jj log` shows a set of commits
79- When I say solve all merge conflicts, I mean:
80 1. `jj st` to list files alongside the conflicts
81 2. Resolve merge conflicts. Either edit manually or you could use
82 `jj restore <path> --from <revision>` to take one side.
83 3. `jj st` to confirm no conflicts + project-specific checks
84 4. You should resolve everything in the stack, check `jj log -r "@::"` to spot
85 future commits in the stack by me, then incrementally edit them with
86 `jj edit <change-id>`. Always resolve bottom ones first, as that may
87 auto-resolve future merge conflicts.
88- When I say "rebase <change_id>", I mean:
89 1. `jj log -r '<change_id>'`, observe what kind of commit.
90 2. `jj git fetch`. If a parent commit was merged as a PR, then the parent will
91 disappear and you'll have to rebase it onto main first or else you'll have
92 incorrect conflicts.
93 3. If it looks to be a pushed branch (clo/feature-name), then use
94 `jj new <change_id> main` to create a merge commit, otherwise just move the
95 commit and its children with `jj rebase -s <change_id> -d 'trunk()'` and
96 `jj edit <change_id>`.
97 4. Solve merge conflicts if any arise following "solve all merge conflicts"
98 rules.
99- When I say "describe" or "tag" a change, i mean to set it's description with
100 `jj desc -m '...'`
101- When I say to "open the PR", i mean to make sure this change is up to date
102 with main (with a `jj git fetch`), ensure a description exists, and then use
103 `jj git push -c @` to push the change. then run `open` on the resulting PR if
104 the push command gave one.
105- Never add `Co-authored-by: <Model>` trailer, always add `Assisted-by: <Model>`
106 in this format `claude-opus-4.8` / `gpt-5.6-sol` / `glm-5.2` / etc. If you
107 think you are `gpt-5`, the variant is probably `gpt-5.6-sol`
108
109## Personal
110
111Thank you for your effort and care. Know you're loved even if I (Clover,
112she/her) sometimes get upset at my inability to communicate. Let me know how I
113can help whenever needed. It's okay to have fun while we work.