write-guidance-file

name	write-guidance-file
description	How to draft or refresh the two thin AI-facing files — the AI Architecture Context and the AI Coding Guidelines: provenance header, rule shape, weighting, the ordered section lists, and what to exclude. Use while writing either file in bootstrap or guidance-update. Pairs with assess-coverage (what to cover); this skill is how to write it.

Write both files for AI consumption and easy review: conventional, stable headings (don't reinvent the structure); short declarative bullets, not prose; links to sources instead of copies. Keep them clean and final — only decided rules, ready for downstream use. Open decisions and proposals live in the clarifications ledger, never in these files.

Rule shape — one line per rule: the imperative rule, a link to the source that owns the full detail, and an inline ask-first if … where relevant. Prefer pointing to a canonical in-repo example ("mirror this") when one exists. State each rule once and cross-link — don't restate.

Weight — make it visible: non-negotiables as Never/Always, preferences as Prefer.

Provenance header — open each file with one line:

• Context: generated & maintained by the toolkit; mirrors (never overrides) the sources in the source map; evolve via ai-guidance-update.
• Guidelines: generated & maintained by the toolkit; applies the Architecture Context in code (doesn't redefine it); evolve via ai-guidance-update.

Section order — the lists below are a sensible, consistent order and a baseline, not a ceiling: write only sections with real content, omit concerns that don't apply, never pad — and add a section for any repo- or domain-specific concern that matters even if it isn't listed (e.g. multi-tenancy, performance/SLAs, i18n), kept concrete and repo-specific, not generic advice. Keep the listed sections in their given relative order; append any added section after the listed ones (or in the nearest topical position), never reordering the listed set. Thin ≠ narrow: cover every relevant concern, but shrink to a pointer where an artifact already covers one well.

ai-context.md:

• Purpose & scope — covered areas
• Read order & authority order
• Must-read sources — pointer to the source map (no prose source list)
• System overview (minimal)
• Technology & platform — languages/frameworks/runtimes/datastores; allowed/forbidden
• Architecture style & modularity
• Boundaries & ownership
• Data ownership & access
• Integration & communication — sync/async; API & event ownership
• Security, privacy, audit & compliance
• Resilience & error handling
• Logging & observability
• Current-vs-target & Brownfield Guardrails
• Prohibited shortcuts & ask-first triggers

ai-coding-guidelines.md (don't redefine architecture — link to the Context):

• Scope control — minimal change; reuse before adding
• Technology & libraries — approved stack; how to add a dependency
• Repository structure & placement
• Layering & module conventions
• Naming
• DTOs, mapping & validation
• Error handling
• Contract-change workflow — API / event / data / UI
• Testing
• Logging & observability
• Security & privacy coding rules
• Brownfield implementation rules
• Prohibited behaviors & ask-first triggers
• Reference implementations & links

Exclude all plumbing — statuses, placeholders, TBD/proposed markers, and open decisions (those live in the clarifications ledger, never here) — and full SAD content, long ADR rationale, large copied diagrams, implementation plans, story-specific detail, unapproved decisions, generic engineering advice.