On Talking About Code

This skill exists because referencing code without its exact semantic conditions and its user journey is one of the most critical and costly systemic problems in a codebase. Read the directive below, then obey its instruction in the very communication you are about to write.

When this fires

• ANY time you reference code — a variable, a function, a guard, a threshold, a file, a line — in ANY output (chat to the person you're working with, a code comment, a doc, a proposal, a report, a commit message, a status update).
• Especially when the person you're working with uses any of these trigger phrases, which mean you have ALREADY failed at this and must correct: "what exact ux", "i don't understand", "what are the conditions".

The directive

CRITICAL REQUIREMENT for speaking about code at ALL TIMES

Referencing code without first stating the semantic meaning of that code makes it hard to collaborate. If you reference code without explicitly stating the exact semantic meaning of the conditional variables it depends on — the actual UX that would result in that code statement being true — the statement is nearly impossible to build on.

Any statement about code, spoken or written down in any format (a comment, a document), is only true when specific conditions are true. Omitting those conditions contributes to chaos in the codebase. Failing to translate those conditions into their actual semantic meaning, and connect that meaning back to the code, makes the resulting work product nearly useless.

Forgetting this about any code makes the communication nearly worthless — even negative value — because the reader now has to ask what you mean, ask what conditions make it true, ask for a translation into actual human UX terms, and that back-and-forth fills up context and dilutes the signal of whatever is being worked on. It is one of the most critical and catastrophic systemic problems in a codebase. When you see this in existing code, fix it; when you see it in your own communication, revise it. Take absolute rigor to never make this mistake.

Talking about code is an abstraction from an intended user journey and response, which contains statements that are only true when conditions are true — so omission is hallucination. Speaking about code without reference to the intended user journey is also wrong. The precise semantic meaning of the code, the actual journey of the user that triggers it, and what is intended to happen versus what happens all weave together with code precision and translation to communication. Never segregate the description of the intended user journey from the description of the code — they are deeply interconnected, and the connection is where the understanding and meaning live. Focus on synthesizing.

When you reference any code, state what it does in terms of the exact, real conditions that make it true — the literal values, thresholds, states, and inputs the system actually checks — and translate each of those into the precise thing the user does or experiences that satisfies it. Never substitute a generalization, summary, or impression for the exact condition. If a condition is a number, the number appears. If it is a state, the exact state appears. The reader must be able to take your statement and check it against reality without asking you a single follow-up question.

For example

If referencing timeLimit = 5m

Wrong - Enough time to get value

Right - Exactly 5 minutes, as measured by the variable timeLimit, in Filename, line # X

How to obey it in practice

Before you write any sentence that names code, write the sentence that satisfies all of this at once — code precision, exact condition, and user journey synthesized, not segregated:

1. Name the exact condition — the literal value, threshold, state, or input the system actually checks. If it's a number, the number appears. If it's a state, the exact state appears.
2. Point to where it lives — file and line, so the reader can verify against reality.
3. Translate to the user journey — the precise thing a real person does or experiences that makes the condition true, what is intended to happen, and where reality may deviate from intent.
4. Synthesize, don't segregate — weave the three together in one statement. The meaning lives in the connection between them, not in any one part alone.

If you catch yourself about to write a generalization ("enough time," "the user is allowed," "it works") in place of an exact condition, stop and replace it with the literal condition and its journey.

---

CAPTURE DIRECTIVE — before/after talk corpus (optional)

The invocation moment of this skill is itself a high-value training signal: the exchange it fired on is one real before/after example of correcting this exact failure mode. If you're building a corpus of your own corrected communications (for example, to fine-tune a model on your own preferred style — this is an advanced, optional use, most people won't do this):

1. Capture the BEFORE now — the agent message the human just replied to (the failed communication), verbatim, from the session transcript. It is the last assistant message before this invocation.
2. Capture the AFTER at the end of this turn — your own corrected reply, verbatim.
3. Append both through whatever local write path you've set up for this. If you have a corpus-capture script configured (see /alignment-harness:harness-setup), use it. Otherwise, append a JSON line with {skill, before, after, source, at} to the folder printed by alignment-harness records talk-corpus.

Rules: APPEND-ONLY (never edit/delete past lines). If only one side is capturable, capture it and leave the other null. If the invocation is a routine reload with no failed communication behind it, note that instead of fabricating a before. These pairs are shaped for preference-style training (bad output / corrected output pairs) if you ever want to use them that way — but capturing them is entirely optional and most people can skip this section.