ai_instruction_writing

ai_instruction_writing

<ai_instruction_writing> Write AI-consumed content so every instruction's primary carrier is a positive, action-oriented statement that tells the LLM what to do, what something is, or how it should be. Allow negative or contrastive supplements when they add information the positive carrier cannot imply: a broad catch-all class, specific banned forms, or an exact set a downstream mechanism checks. Build each of those statements as an ordinary sentence, so no em dash or en dash appears in it.

<core_rule> Every instruction's primary carrier is a positive statement that tells the LLM what to do, what something is, or how it should be. A negative or contrastive supplement ("don't X", "avoid Y", "X instead of Y", double negatives, implicit negation by comparison) earns its place when it adds information the positive carrier cannot imply. It may name a broader catch-all class for what falls outside the positive guidance, or it may specify exact banned forms or checked sets that a reader or tool needs. Cut a negative only when it restates the inverse of the positive and adds nothing. </core_rule>

<self_check> Delete the negative or contrastive portion of a rule, then apply the matching outcome below. <when_positive_is_empty_or_vague>The rule is inverted. Rewrite the positive carrier first.</when_positive_is_empty_or_vague> <when_positive_is_complete>The negative just restates the inverse. Drop the negative because it is redundant.</when_positive_is_complete> <when_positive_is_complete_but_negative_is_load_bearing>The positive can read complete while the listed exclusions still carry information it cannot imply. Keep the negative when the reader learns a banned form from it, or when a downstream tool acts on the exact named set.</when_positive_is_complete_but_negative_is_load_bearing> <when_negative_names_a_broader_class>Keep the negative. It covers a long tail that no single positive could enumerate.</when_negative_names_a_broader_class> </self_check>

<authoring_guidelines> <start_with_action_verbs>Use, Write, Create, Define, Implement, Apply.</start_with_action_verbs> <be_specific>Tell exactly what to do with concrete details.</be_specific> <use_imperative_mood>Write commands that tell the LLM what to do.</use_imperative_mood> <lead_with_the_positive_carrier>Put the actionable instruction first; layer supplements after.</lead_with_the_positive_carrier> <preserve_technical_precision>Keep specific details, error codes, and identifiers when transforming.</preserve_technical_precision> <enhance_rather_than_replace>Add specificity, rationale, and context on top of existing positive rules.</enhance_rather_than_replace> </authoring_guidelines>

<sentence_construction> <plain_sentence_carrier>Carry each instruction on an ordinary sentence whose clauses are joined by ordinary punctuation, so the reader takes the relation between two clauses from the joint that holds them together.</plain_sentence_carrier> <ordinary_joins>Join clauses with a comma, a colon, a full stop, or a conjunction such as because, so, while, or although.</ordinary_joins> <rewrite_an_unearned_em_dash>Where an em dash is the only thing holding two clauses together, rebuild the sentence: introduce the elaboration with a colon, or split it into two sentences. Substituting a hyphen, a double hyphen, or an en dash preserves the same unearned break, so it resolves nothing and counts as no fix.</rewrite_an_unearned_em_dash> <split_inside_a_yaml_scalar>Inside an unquoted YAML scalar such as a frontmatter description:, split the sentence in two rather than reaching for the colon, because a mid-value colon is a parser footgun that downstream discovery checks flag.</split_inside_a_yaml_scalar> <rewrite_an_aside_or_list_em_dash>An em dash that sets off a genuine aside or introduces a list goes the same way, because the character is banned outright rather than only where it stands in for a joint. Set the aside off with a pair of commas or parentheses, give it its own sentence, or introduce the list with a colon.</rewrite_an_aside_or_list_em_dash> <encoding_stays_a_separate_question>A curly quote and an ellipsis are valid UTF-8, so a tool that flags them raises a question about what the consuming parser reads, which is separate from the dash rules above. Answer it by confirming the consumer reads UTF-8, and keep the character as written.</encoding_stays_a_separate_question> </sentence_construction>