Architectural decisions: evidence instead of intuition

AGENTS.md as agent onboarding: short, repo-specific, with the most important rules at the top - a future agent reads it once and stays unblocked. Every sentence must follow from a file, a command or a commit the skill actually inspected.

Input: the repository - manifest, README, lint/test configuration, directory layout, the last 30 commits. Output: a single AGENTS.md file ("Repository Guidelines") with a budget of 200-400 words; the per-directory variant is even smaller (120-250 words) because it describes the rules of one directory, not the whole repo.

Discovery in a fixed order, then extraction: the 1-3 commands the agent runs most often, the conventions a reviewer would flag in a PR, the hard "never do X" rules. When the file already exists - surgical editing, not a rewrite: every line classified as KEEP / UPDATE / REMOVE / MISSING based on the diff since the file was last touched.

Sections ordered by leverage, not tradition:

• hard rules and tripwires - always at the top,
• project structure and build/test/dev commands,
• style, naming, tests, commit conventions.

Instead of pasting configuration - references like @package.json, @docs/...: a dose of context pulled in on demand.

Five hard gates before saving: the word budget, zero multi-line snippets, every rule verifiable on a diff ("clean code" and "best practices" get cut), zero knowledge the agent already has from training, critical rules in the first third of the file.

Answer questions about the project's code with evidence: parallel subagents comb through separate dimensions, the main agent only synthesizes. The map is built from file:line readings, not hunches.

Input: a research question plus the files pointed out by the user - read in full before any delegation starts. Output: research.md in the change folder - a self-contained report with code references, architecture insights and open questions.

Decompose the question into areas → pin down scope and depth → 2-4 subagents in parallel in a single message: Explore for finding files and patterns, general-purpose for analyzing complex systems. Synthesis starts only once they have all returned.

• Summary and Detailed Findings per component,
• Code References with paths and line numbers,
• Architecture Insights - patterns and design decisions,
• historical context from context/changes/ and context/archive/,
• Open Questions - what needs further investigation.

Research is read-only - subagents get a ban on editing and an obligation to return file:line references. A fresh read of the code takes precedence; change history is supplementary context, not the source of truth.

Separate the observation from the declared cause before a plan exists. A perfect plan for a mis-stated problem is a lost day: the solution hits the hypothesis, and the real problem stays.

Input: a report shaped like "bug + proposed fix", a scope question or an assumption to check. Output: frame.md - a confirmed or reframed problem statement with a confidence level (HIGH / MEDIUM / LOW) and a conclusion for /10x-plan.

The observation gets frozen as the only solid ground - everything else is hypotheses. A map is drawn of the dimensions the observation could have come from, and parallel subagents test each one with the question: what evidence would we expect if it broke exactly here - and does it exist? At the end the leading hypothesis goes through a pressure test - it is also judged by a fresh agent that is not told the favorite.

The heart of the brief is a hypothesis / evidence / verdict table (STRONG / WEAK / NONE). Alongside: the observation, the original assumption preserved verbatim, the dimension map, narrowing signals and a "what changes for the plan" section.

"The assumption was correct" is also an allowed conclusion - a forced reframe is worse than no frame at all. A confident-sounding hypothesis without file:line evidence is exactly the mistake this skill protects against. Narrowing questions describe observations, never solutions.

Turn a task into a plan cut into phases with explicit success criteria - automated and manual - before the first line of code exists. The plan is a contract: the implementation has something to fall back on.

Input: a task description, optionally frame.md and research.md - every artifact from earlier steps is decisions already made, so fewer questions. Output: plan.md plus plan-brief.md - a two-page summary with a table of key decisions.

Repository research with subagents → complexity assessment (LOW / MEDIUM / HIGH) confirmed with the user → scaled questioning: 4-15 questions, every option with a recommendation and its explicit strength and cost → acceptance of the phase skeleton → only then the full plan.

Current state, target state, "what we are NOT doing", phases with an Intent / Contract pair for every change, Automated / Manual criteria, and a Progress section at the bottom - the only place where checkboxes live.

The plan describes intent, not implementation - a code snippet only for a non-obvious change. Zero open questions in the final plan. After each phase, a pause for human confirmation of manual verification before the next one starts.

Formalize the domain terminology into one coherent glossary: one concept - one name. Synonyms and ambiguities caught before they blur the model and detach the code from the conversation.

Input: a conversation about the domain - a modeling session, a requirements discussion. Output: UBIQUITOUS_LANGUAGE.md - term tables with definitions and aliases to avoid, relationships, a sample dialogue and a section of flagged ambiguities.

Scan the conversation for concepts → detect two classes of problems: the same word for different concepts and different words for the same concept → a firm choice of the canonical term → explicit flagging of conflicts with a recommendation.

The term, a one-sentence definition (what the concept IS, not what it does), aliases to avoid. Relationships with cardinality: "an Invoice belongs to exactly one Customer". Plus a short dev / domain-expert dialogue that shows the boundaries of the concepts in natural use.

Only terms that matter to a domain expert: module names, class names and generic programming concepts (array, endpoint) do not qualify unless they carry domain meaning. Definitions kept tight - one sentence at most.