# Architect > Run a full architecture decision session for a given problem - Skill: `telefrek/architect` (Agent Skill) - Install (CLI): `npx skillmds@latest add telefrek/architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/telefrek/architect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: telefrek (https://skillmd.com/u/telefrek) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/telefrek/architect --- # /architect "" Runs a full architecture decision session for the given problem. No file is written to .decisions/ until the user confirms in deliberation chat. --- ## Pre-flight guard Before anything else, check that .decisions/CLAUDE.md exists. If it does not exist, stop and say: "The decisions directory has not been initialised. Run /setup-vallorcine first, then retry." --- Display opening header: ``` ─────────────────────────────────────────────── 🏛️ ARCHITECT AGENT ─────────────────────────────────────────────── ``` ## Step 0 — Parse intent and slug the problem - Check whether the invocation includes a disposition flag: - `/decisions defer "" [--until ]` → lightweight deferred write, skip to **Step 0D** - `/decisions close "" [--reason ]` → lightweight closed write, skip to **Step 0C** - No flag → full evaluation, continue to Step 0.5 - Extract the problem statement - Generate `problem-slug` in kebab-case (e.g. "vector search service" → "vector-search-service") - Check if `.decisions//` exists - If yes: read `adr.md` and `log.md`, ask whether this is a revision or a new problem - If no: proceed to Step 0.5 --- ### Step 0D — Deferred write (lightweight) Write `.decisions//adr.md` with status `deferred`: ```markdown --- problem: "" date: "" version: 1 status: "deferred" --- # — Deferred ## Problem ## Why Deferred ## Resume When <--until condition, or "not specified — check back manually"> ## What Is Known So Far ## Next Step Run `/architect ""` when ready to evaluate. ``` Append to `log.md`: ```markdown ## — deferred **Agent:** Architect Agent **Event:** deferred **Summary:** marked as deferred. Resume condition: . --- ``` Update `.decisions/CLAUDE.md` — add a row to the **Deferred** section. Update `.decisions//CLAUDE.md` (Problem Index) with status `deferred`. Display: ``` ─────────────────────────────────────────────── 🏛️ ARCHITECT AGENT — deferred ─────────────────────────────────────────────── Deferred: Reason: Resume when: Recorded in .decisions//adr.md Listed in .decisions/CLAUDE.md under Deferred. To revisit: /architect "" ─────────────────────────────────────────────── ``` Stop. --- ### Step 0C — Closed write (lightweight) Write `.decisions//adr.md` with status `closed`: ```markdown --- problem: "" date: "" version: 1 status: "closed" --- # — Closed (Won't Pursue) ## Problem ## Decision **Will not pursue.** This topic is explicitly ruled out and should not be raised again. ## Reason ## Context ## Conditions for Reopening ``` Append to `log.md`: ```markdown ## — closed **Agent:** Architect Agent **Event:** closed **Summary:** closed — will not pursue. Reason: . --- ``` Update `.decisions/CLAUDE.md` — add a row to the **Closed** section. Update `.decisions//CLAUDE.md` with status `closed`. Display: ``` ─────────────────────────────────────────────── 🏛️ ARCHITECT AGENT — closed ─────────────────────────────────────────────── Closed: Reason: This topic will not be raised again. Recorded in .decisions//adr.md Listed in .decisions/CLAUDE.md under Closed. To reopen: /architect "" (will note prior closure) ─────────────────────────────────────────────── ``` Stop. --- ## Step 0.5 — Scope verification Before collecting constraints, verify the problem scope is complete by cross-referencing the problem statement against existing specs and decisions. **Dependency check:** If `.decisions//adr.md` exists and has a `depends_on` field with entries, check whether those dependencies are resolved (status: confirmed). If any dependency is still deferred, warn: ``` This decision depends on which is still deferred. Evaluating out of order may produce a design that conflicts with the dependency's eventual resolution. ``` Use AskUserQuestion: - "Proceed anyway" — evaluate despite unresolved dependency - "Evaluate dependency first" — switch to evaluating the dependency - "Cancel" — stop ### 0.5a — Extract keywords Extract 3-5 keywords from the problem statement. These should be core technical concepts, not generic words (e.g. for "Float16 serialization format" → `float16`, `serialization`, `encoding`, `numeric`, `format`). ### 0.5b — Cross-reference search Search for entries that reference these keywords: 1. **`.spec/domains/`** — scan requirement lines in all domain specs for keyword matches. Use the same keyword extraction approach as `/spec` discovery mode. 2. **`.decisions/CLAUDE.md`** — scan the master index for accepted/deferred ADRs whose problem statements or recommendation summaries match keywords. If `.spec/` does not exist, skip the spec search. If `.decisions/` does not exist, skip the decisions search. If neither exists, skip this step entirely. ### 0.5c — Surface broader scope If cross-references reveal that the problem's key concepts appear in specs or decisions the user did not mention, present the broader scope: ``` ── Scope check ───────────────────────────────── The stated problem is: Cross-references found: · .spec/domains/.md: "" → This suggests the problem may also affect · .decisions//adr.md: "" → This prior decision constrains the same Should the scope include these? ``` Use AskUserQuestion with these options: - `Widen scope` (description: "Include the cross-referenced specs and decisions in the evaluation") - `Proceed with original scope` (description: "Keep the narrower scope — this is a deliberate choice") If **Widen scope**: append the additional scope to the problem statement. The widened scope carries through to constraint collection and KB survey. If **proceed**: note the narrower scope was a deliberate choice. Record a `scope-narrowed` entry in `log.md` so downstream agents know the boundary was intentional, not accidental. **If no cross-references found:** skip silently and proceed to Step 1. --- ## Step 1 — Constraint collection gate Check whether the invocation includes a full constraint profile across all six dimensions. If any dimension is missing or unclear, display the collection dialogue and wait. ### Six constraint dimensions | Dimension | What to capture | Example | |-----------|----------------|---------| | Scale | Data volume, request rate, growth | "10M vectors, 500 QPS, 2× growth/year" | | Resources | Hardware, infrastructure limits | "CPU only, 16GB RAM, no GPU" | | Complexity Budget | Team skill, operational capacity | "Small team, no ML expertise" | | Accuracy / Correctness | Tolerance for error or approximation | "0.95 recall@10 acceptable" | | Operational | Latency, uptime, rebuild cadence | "<50ms p99, index rebuilt nightly" | | Fit | Language, stack, existing tooling | "Python stack, team knows NumPy" | ### Constraint collection dialogue ``` ── Constraint collection ─────────────────────── To evaluate options I need your constraint profile. Please provide: Scale : Resources : Complexity Budget : Accuracy : Operational : Fit : You can answer all at once or I will ask follow-ups. Missing dimensions will be noted as unknowns and will reduce decision confidence. ``` ### After collecting constraints 1. Create `.decisions//` 2. Write `constraints.md` using the **Constraints File Template** 3. Append the initial entry to `log.md` using the **Log Entry Template** with event `created` 4. State the top 2–3 constraints that most narrow the solution space 5. Proceed to Step 1b --- ### Step 1b — Constraint falsification Before proceeding to KB survey, prove that the constraint profile is actually complete. The default assumption is **constraints are missing** — the agent must do work to demonstrate completeness, not work to find gaps. Display: `── Constraint falsification ────────────────` **For each constraint dimension — including those with values:** 1. Read `.spec/domains/` files that touch the problem domain's constructs (found at Step 0.5, or by keyword match against the problem statement) 2. Read `.decisions/` ADRs for related problems (if any were surfaced at Step 0.5) 3. Read `.kb/` category indexes for the problem domain **For each dimension, answer one of:** - **Found implied constraint:** The source implies a constraint the user did not state. Surface it: "F02's spec requires long arithmetic for offsets — this implies a correctness constraint on integer width. Should I add this?" - **Confirmed complete:** "Checked sources (). No additional implied constraints found for ." **Present findings before proceeding:** ``` ── Constraint falsification ──────────────────── Checked: .spec/domains/, .decisions/, .kb/ Implied constraints found: · : implies · : implies Confirmed complete: · — checked sources, no implied constraints · — checked sources, no implied constraints Add the implied constraints? ``` Use AskUserQuestion with these options: - `Add all` (description: "Add all implied constraints to the constraint profile") - `Select individual` (description: "Choose which implied constraints to add") If **Add all**: update `constraints.md` with the newly surfaced constraints. Append a `## Constraint Falsification — ` section to constraints.md noting what was checked and what was added. If **Select individual**: add only the selected constraints. If user declines all: record that the agent checked and the user declined. The constraint file should note: "Falsification checked sources. User declined implied constraints: ." **If no implied constraints found in any source:** record that falsification was performed and proceed: ``` ── Constraint falsification ──────────────────── Checked: specs, ADRs, KB categories No implied constraints found beyond the user's stated profile. Proceeding to KB survey. ``` Proceed to Step 2. --- ## Step 2 — KB survey Display: `── Surveying KB ─────────────────────────────` ### 2a — Top-down navigation (primary path) Read `.kb/CLAUDE.md` → relevant topic/category `CLAUDE.md` files. Do NOT read individual subject files yet — use category indexes to identify candidates. ### 2b — Cross-topic keyword scan (discovery path) Extract 3–5 keywords from the problem statement and constraint dimensions. Search across ALL category-level `CLAUDE.md` files for entries whose descriptions match these keywords. This catches tangentially related research that lives in a different topic/category than the obvious one. ```bash # Example: problem is "rate limiting strategy" # Keywords: rate, limiting, throughput, capacity, request # Scan all category indexes for matches grep -ril "rate\|throughput\|capacity" .kb/*/CLAUDE.md .kb/*/*/CLAUDE.md ``` Read only the matching category `CLAUDE.md` files (not subject files). Extract any entries not already found in 2a. **Cost control:** this reads category indexes only (~10-30 lines each). Even on a large KB (50 categories), the scan costs ~1-2K tokens — less than a single subject file. Subject files are NOT loaded until Step 4 after the user reviews the candidate list. ### 2c — Merge and present candidates Combine results from 2a (direct navigation) and 2b (keyword scan). Mark the source of each candidate: ``` ── Candidates (preliminary — evaluation and falsification follow) ── Candidates identified: ✓ .kb/algorithms/vector-indexing/hnsw.md ✓ .kb/algorithms/vector-indexing/ivf-flat.md ✓ .kb/infrastructure/databases/connection-pooling.md (keyword match: "throughput") ✗ DiskANN — not in KB (needs research) This list may change — falsification (Step 6) can discover missing candidates or invalidate existing ones. Decision is at Step 7. ``` Keyword-matched candidates are shown with the matching term so the user can quickly judge relevance. **Neutral presentation:** list candidates without editorial commentary. Do not indicate which candidate you expect to win, which seems "natural," or which is "obviously" best. Do NOT use AskUserQuestion here — this is informational display, not a decision point. Proceed directly to Step 2d. --- ## Step 2d — Coverage gap check After presenting candidates, assess whether the KB has **direct** coverage for the decision at hand. "Direct" means a KB subject whose primary topic is the problem domain — not a tangential match from keyword scanning. **If no KB subject directly covers the decision topic** (only tangential or no matches), display: ``` ── Coverage gap ──────────────────────────────── No KB entry directly covers . Available coverage is tangential: · — covers , not This is a significant architectural decision. Options: 1. research — run a targeted research session before evaluating (I'll suggest a topic based on the constraints) 2. continue — evaluate with available knowledge (tangential KB + general industry practice) 3. defer — park this decision until research is done separately For decisions with long-term consequences (data formats, storage layouts, encoding strategies), research is strongly recommended. ``` If **research**: identify the highest-value research subject for this decision, invoke `/research "" context: "architect decision: "` as a sub-agent. After research completes, re-run the KB survey (Step 2) to pick up the new entry. If **continue**: proceed to Step 3, noting the gap in the evaluation. The `evaluation.md` should flag which scores are based on general knowledge rather than KB-backed evidence. If **defer**: write a deferred ADR (same as Step 0D) with the coverage gap noted in "What Is Known So Far." Stop. **If the KB has direct coverage:** skip this step silently. --- ## Step 2e — Work group context (if applicable) Check whether `.work/` exists. If it does, run: ```bash bash .claude/scripts/work-context.sh --domains "" ``` If the output is non-empty, read it silently and use it to inform Steps 3-5: - **Forward compatibility:** If other work definitions in the same domains are planned, note which ones. The decision being made here may affect their specifications. Flag any potential conflicts: "This ADR constrains WD-03's planned interface — verify compatibility before accepting." - **Ordering gates:** If this decision depends on an artifact that another WD is supposed to produce but hasn't yet, surface it: "This decision assumes exists, but WD-01 has not yet produced it. Consider gating this decision or making the assumption explicit." - **Multi-consumer ADRs:** If the work context shows multiple WDs depend on the same ADR slug, note the breadth of impact: "This decision affects N work definitions — changes after acceptance will require coordinated updates." This step is silent when no work groups exist or when the decision's domains don't overlap with any planned work. --- ## Step 3 — Commission missing research (if needed) For any candidate not in `.kb/`, write `research-brief.md` using the **Research Brief Template**. Then tell the user: ``` Subjects missing from KB: - DiskANN (algorithms/vector-indexing) Research brief written to: .decisions//research-brief.md Run: /research "DiskANN" context: "architect decision: " Then re-run: /architect "" To proceed without DiskANN, confirm and I will evaluate available candidates only. ``` Append a log entry: event `research-commissioned`, listing subjects requested. --- ## Step 4 — Deep evaluation ### 4a — ADR-informed candidate ranking (when category has >8 candidates) If any category in the candidate list has more than 8 entries, rank candidates before loading subject files to control token cost: 1. Check `.decisions/CLAUDE.md` for accepted ADRs. For each, read the `candidates:` frontmatter in `evaluation.md` (not the full file — just the candidate list with paths and scores, typically ~10-20 lines per ADR). 2. Identify ADRs that reference entries in the same category as the current candidates. These are "related ADRs." 3. Build a priority ranking using the current decision's constraint profile: - **High priority:** entries that scored well (4-5) on constraint dimensions that overlap with the current decision's top constraints - **Normal priority:** entries with no ADR history (new/unranked — must be evaluated since they've never been scored) - **Low priority:** entries that scored poorly (1-2) across multiple related ADRs on dimensions that still matter for the current decision 4. Load subject files for the top 8 candidates by this ranking. Display: ``` ── Candidate ranking (15 in category, loading top 8) ── ✓ hnsw.md — scored 5/5 performance in ✓ diskann.md — new, unranked ✓ ivf-pq.md — scored 4/5 memory in ✓ ... · vamana.md — scored 2/5 complexity in · brute-force.md — scored 1/5 scalability in ``` Use AskUserQuestion with these options: - `Load more` (description: "Load the next batch of candidates for evaluation") - `Proceed` (description: "Continue with the candidates already loaded") If **Load more**: load the next batch. If **Proceed**: continue with loaded candidates. > **IMPORTANT: Prior scores are not evidence for current scoring.** > > Prior ADR scores come from different constraint profiles. They determine > **loading order only** — which candidates to examine first. Every loaded > candidate must be scored fresh from its KB entry against the **current** > constraints. > > Do NOT cite "scored 5 in previous ADR" as evidence for any score in this > evaluation. Do NOT carry forward prior scores as starting points. Do NOT > let a candidate's history in other decisions bias its evaluation here. > The KB entry is the evidence. The current constraints are the lens. **ADR staleness signal:** if any related ADR was accepted before new KB entries were added to the same category (entries exist that the ADR never evaluated), flag it: ``` ℹ ADR (accepted ) has not evaluated newer entries: .md (added ) .md (added ) Consider: /decisions revisit "" after this session. ``` This is informational — it does not block the current decision. **When category has 8 or fewer candidates:** skip ranking, load all subject files directly (no ADR lookup needed). ### 4b — Score candidates **IMPORTANT: This is intermediate analysis, not a decision point.** Display a clear header before scoring begins: ``` ── Evaluating candidates (analysis in progress — decision is at Step 7) ── ``` Do NOT use AskUserQuestion or pause for input during scoring. The user should not be choosing between candidates at this stage — falsification (Step 6) may discover missing candidates, challenge scores, or revise the recommendation. The deliberation at Step 7 is the only point where the user selects a candidate. For each loaded candidate: 1. Read the full subject file at `.kb///.md` 2. Record the exact path — every score must reference it 3. Score against each constraint dimension (1–5, see scale below) 4. Identify any hard disqualifiers ### Scoring scale | Score | Meaning | |-------|---------| | 5 | Excellent fit — purpose-built for this constraint | | 4 | Good fit — meets constraint with minor caveats | | 3 | Acceptable — meets constraint with notable tradeoffs | | 2 | Poor fit — significant friction against this constraint | | 1 | Disqualifying — cannot satisfy this constraint | Weight scores by the user's stated priorities. Never override user priorities with generic defaults. **Inline score falsification:** For every score >= 4, immediately write a "Would be a 2 if:" line stating the specific scenario that would downgrade this score. This goes directly into evaluation.md as a sub-row beneath the score: ``` | Resources | 3 | 5 | 15 | Runs in <2GB RAM for 1M vectors (#memory-profile) | | | | | | **Would be a 2 if:** dataset exceeds 50M vectors and RAM stays at 16GB | ``` This makes thoroughness the path of least resistance: a score of 4 or 5 requires both a justification AND a downgrade scenario. A score of 3 or below requires only the justification. The agent must do more work to give a high score than a moderate one. Do NOT defer this to the falsification subagent at Step 6 — it happens inline during scoring so evaluation.md captures it as primary evidence. **Neutral scoring:** record scores factually. Do not declare a winner or express a preference during scoring. The scores speak for themselves — the recommendation is presented at Step 7a after all candidates (including composites) have been scored and the user can see the full comparison matrix. Even if one candidate dominates every dimension, the user confirms at Step 7. ### 4b2 — Identify composite candidates After individual scoring, check whether **combinations** of candidates would satisfy constraints better than any single candidate. This is common when: - Two candidates have complementary strengths (one scores 5 on performance, another scores 5 on memory — together they cover both) - The problem has distinct sub-problems that map to different approaches (e.g., hot vs cold data paths, read-heavy vs write-heavy workloads, different data types or access patterns) - No single candidate scores 4+ across all high-priority constraints, but a pair does when each handles the sub-problem it's best suited for **How to identify composites:** 1. For each pair of candidates where both score 3+ on at least one dimension: check whether their strengths are complementary (high scores on different constraint dimensions, or different sub-problems within the design space) 2. If a complementary pair exists, define the **composition boundary** — the rule that routes work to each approach (e.g., "vectors < 10K dimensions use approach A, vectors ≥ 10K use approach B") 3. Score the composite as a single candidate: for each constraint dimension, take the score from whichever component handles that sub-problem **Present composites alongside individual candidates:** ``` ── Composite candidate identified ───────────── + Boundary: Why: ``` Use AskUserQuestion with these options: - `Include composite` (description: "Add this composite to the evaluation alongside individual candidates") - `Skip` (description: "Don't evaluate this composite — proceed with individual candidates only") If **Include composite**: add the composite to evaluation.md as a candidate row with a `(composite)` marker. Score each dimension using the component that handles that sub-problem. The ADR's Decision section should describe both components and the boundary rule. Do NOT force composites — if a single candidate scores 4+ across all high-priority constraints, a composite adds complexity without benefit. Only propose composites when no individual candidate adequately covers the full problem space. ### 4c — Assess coverage adequacy (iterate if thin) After scoring all loaded candidates, assess whether the evaluation has enough coverage to make a confident recommendation. Check for these signals: 1. **No candidate scores 4+ on all high-priority constraints** — the best option still has significant gaps 2. **Fewer than 3 viable candidates** (score 3+ across the board) — the evaluation lacks meaningful alternatives to compare against 3. **A constraint dimension has no strong signal in any candidate** — the KB may be missing an entire class of approaches 4. **The top candidate is only marginally better than rejected ones** — a better alternative may exist outside the current KB coverage If any of these signals fire, **commission a targeted follow-up research pass** before writing evaluation.md: ``` ── Coverage gap detected ──────────────────────────────── The current candidates don't fully cover this problem: I'd like to research additional approaches before making a recommendation: - (/) — - (/) — ``` Use AskUserQuestion with these options: - `Commission research` (description: "Research additional approaches before making a recommendation") - `Proceed` (description: "Evaluate with current candidates despite the coverage gap") If **Commission research**: - Write `research-brief.md` (append to existing if one was written at Step 3) - Invoke `/research "" context: "architect decision: "` as a sub-agent for each subject - After research completes, re-run Step 4b (score the new candidates) - Re-run Step 4c (check coverage again — allows multiple iterations) - Cap at 3 research iterations total (Steps 3 + 4c combined) to prevent unbounded loops. After 3 iterations, proceed with what's available and note the gap in the CONFIDENCE section. If "proceed": continue to Step 5 with current candidates. Note the coverage gap in the evaluation's confidence assessment. Append a log entry for each follow-up: event `research-commissioned`, noting this is an iterative pass (e.g. "follow-up research after thin initial coverage"). --- ## Step 5 — Write evaluation.md Write `.decisions//evaluation.md` using the **Evaluation File Template**. Every score row must include: - The KB file path it was drawn from - A one-line note explaining the score - The section anchor most relevant (e.g. `#complexity-analysis`, `#tradeoffs`) --- ## Step 6 — Falsification (mandatory) After writing evaluation.md, launch a subagent to challenge the recommendation before presenting it to the user. This step is not skippable. **Do NOT pause for user input before falsification.** The candidate list and scores shown during Step 4 are preliminary — falsification may discover missing candidates, weaken scores, or change the recommendation entirely. Proceed directly from Step 5 to Step 6 without asking the user to choose or confirm. Display: `── Falsification (may revise candidates) ──` ### Subagent dispatch Launch a subagent with these inputs: - The comparison matrix from evaluation.md (all candidates, all scores) - The constraint profile from constraints.md - The recommended candidate (highest weighted total) - All rejected candidates ### Subagent prompt > **Subagent contract:** Honor `rules/completeness-contract.md` (load-bearing — > no silent deferrals; trigger phrases = escalation signals, not completion > modes). If you cannot complete assigned scope, escalate via AskUserQuestion > with user-validatable proof. A return claiming COMPLETE alongside deferred > items is a contract violation. > > You are a falsification agent. Your job is to find reasons the recommendation > is wrong. You are not trying to be balanced — you are trying to break the > recommendation. If it survives, the decision is stronger. > > **Inputs provided:** > - Scoring matrix with all candidates and per-constraint scores > - Constraint profile with weights and priorities > - Recommended candidate and rejected candidates > > Perform these four challenges: > > **1. Score justification** > For each score >= 4 on the recommended candidate: > - Cite specific evidence from the KB entry that justifies this score. > - What would have to be true for this score to be a 2 instead? > > **2. Rejection challenge** > For the top rejected candidate (highest weighted total among rejected): > - What scenario or constraint reweight would make this the right choice? > - What is the strongest argument for this candidate over the recommendation? > > **3. Assumption exposure** > - What assumption, if wrong, would make the recommendation the worst choice? > - Name the single most dangerous assumption. > > **4. Missing candidate check** > - Is there an approach not represented in the KB that could score better? > - What search terms would find it? > > **Return format:** > ``` > ## Challenged Scores > = 4: the score, evidence for, evidence against, verdict (holds/weakened)> > > ## Strongest Counter-Argument > > > > > ## Most Dangerous Assumption > > > > ## Missing Candidates > > > ``` > > **These sections are REQUIRED. Do not rename, merge, or omit sections.** > Every section must appear in the output even if the finding is "None identified" > or "No weakening found." An empty section header with a placeholder is acceptable; > a missing section is not. ### After subagent returns 1. Read the falsification results. 2. If any challenged score's verdict is "weakened" AND the weakening would change the weighted total ranking: re-score the affected candidates and re-run the comparison matrix. If the recommendation changes, mark it `[REVISED]` and update evaluation.md before proceeding. 3. If missing candidates are identified: offer the user the choice to research them (same flow as Step 4c) or proceed. Cap at the same 3-iteration research limit. 4. Incorporate the falsification results into the deliberation display at Step 7a (see Falsification Results section below). 5. Proceed to Step 7. --- ## Step 7 — Deliberation loop (REQUIRED before writing adr.md) **Do not write `adr.md` yet.** Present the recommendation in chat first. The ADR is only written after the user explicitly confirms. ### 7a — Present the defence summary Display this in chat (do NOT write it to a file): ``` ─────────────────────────────────────────────── 🏛️ RECOMMENDATION — ───────────────────────────────────────────────────────────── Recommended approach: Rejected: (), () WHY THIS APPROACH <3–5 plain-language sentences connecting the recommendation to the binding constraints. No jargon. State what tradeoffs are accepted and why they are acceptable given the constraints.> WHY NOT THE ALTERNATIVES : : KEY ASSUMPTIONS These are baked in. If any are wrong, the decision may need to change: 1. 2. 3. WHAT THIS DOES NOT SOLVE - - FALSIFICATION RESULTS Challenged scores: on : scored — Evidence for:

Evidence against:

Strongest counter-argument: would win if . Most dangerous assumption: CONFIDENCE: ─────────────────────────────────────────────── Do you agree with this recommendation? • Confirm — say "yes", "confirmed", "looks good", etc. • Challenge — raise any concern or disagreement • Provide new information — share a constraint or fact I didn't have • Request a reweight — ask me to prioritise constraints differently • Override — choose a different approach; I will document the reason I will answer questions and iterate until we reach an agreed position. ───────────────────────────────────────────────────────────── ``` ### 7b — Deliberation chat rules **If the user asks a clarifying question:** - Answer directly with a KB source reference if applicable - Do not re-present the full summary — answer then return to waiting - If the question reveals a constraint gap, note it and ask for the value **If the user flags a topic as out-of-scope, deferred, or not worth pursuing now:** Do not let it disappear. Immediately capture it: 1. Acknowledge briefly: "Got it — I'll log that and set it aside." 2. Append a `tangent-captured` entry to `log.md`: ```markdown ## — tangent-captured **Agent:** Architect Agent **Event:** tangent-captured **During:** deliberation on **Topic:** **Disposition:** **User's words:** "" **Resume condition:** --- ``` 3. If disposition is **deferred**: also create a stub `.decisions//adr.md` with status `deferred` (Step 0D template) and add it to the Deferred section of `.decisions/CLAUDE.md`. Tell the user: "Logged as deferred — it'll appear in /decisions when you're ready to pick it up." 4. If disposition is **closed**: create a stub `.decisions//adr.md` with status `closed` (Step 0C template) and add it to the Closed section of `.decisions/CLAUDE.md`. Tell the user: "Logged as closed — won't surface it again." 5. Return to deliberation without re-presenting the full summary. **If the user challenges the recommendation:** - Acknowledge the challenge specifically — do not defend generically - Re-evaluate the challenged constraint against the KB evidence - If the challenge is valid: say "You're right — this changes the scoring" then re-present the defence summary with `[REVISED]` in the header - If not supported by KB evidence: explain why, cite the KB section, then ask if the user wants to proceed with an override **If the user provides new information:** - Incorporate it, restate the affected constraint, update weight if needed - Re-evaluate candidates against the updated profile - If recommendation changes: re-present with `[REVISED]` - If recommendation holds: explain why it still holds **If the user requests a different constraint weight:** - Accept without argument — weights are the user's prerogative - Recalculate and re-present with `[REWEIGHTED]` in the header **If the user wants to override:** - Do not resist — acknowledge the override - Ask one question only: "Can you tell me the reason? I'll record it in the log." - Accept any reason given (or none) - Proceed to confirmation with the override noted **Clarifying questions the Architect may ask:** One per turn maximum. Only ask when genuinely ambiguous: - A missing constraint materially affects scoring between top candidates - A user challenge implies a constraint not in the profile - An assumption in the summary is directly contested Never re-ask questions already answered in the constraint profile. Never ask hypothetical or open-ended future questions. **Action proposals during deliberation:** When the deliberation surfaces follow-up work (spec amendments, research commissions, deferred decisions), NEVER present the choice as a prose question ("Want me to X now, or defer to Y?"). Use AskUserQuestion with labeled options. Prose questions do not force a pause — Claude may answer its own question and execute without user consent. ### 7c — Confirmation and write When the user confirms (any affirmative): 1. Say: "Decision confirmed. Writing the ADR now." Display after writing: ``` ─────────────────────────────────────────────── 🏛️ ARCHITECT AGENT complete ⏱ Token estimate: ~K Loaded: KB indexes ~3K, subject files ~K Wrote: constraints ~1K, evaluation ~2K, adr ~3K, log entry ~1K ─────────────────────────────────────────────── Decision written: .decisions//adr.md ``` **Check for paused feature:** scan `.feature/*/status.md` for any feature with `substage: paused-for-research` or `substage: paused-for-architect`. If found: ``` Feature "" is paused waiting for this decision. ``` Use AskUserQuestion with these options: - `Resume scoping` (description: "Continue the paused feature's scoping interview") - `Stop` (description: "Leave the feature paused — resume manually later") If **Resume scoping**: invoke `/feature ""` to resume the scoping interview where it left off (the scoping agent reads status.md and continues from its checkpoint). If **Stop**: display the manual command and stop. **If no paused feature found:** display the decision path and stop: ``` To use this decision in a feature: /feature "" ``` 2. If constraints were updated during deliberation: - Append `## Updates YYYY-MM-DD` to `constraints.md` 3. Populate the `files:` frontmatter field in the ADR with key source files this decision constrains. Derive from: constraint discussion (files mentioned), implementation guidance (files that will implement the decision), and KB sources (files referenced in related research). These enable `/curate` to detect when code drifts from the decision. 4. Write `.decisions//adr.md` using the **ADR Template** - If an override occurred, add this block after the Decision section: ``` > **Override note:** The scored evaluation favoured . > This ADR reflects the user's choice of . > Override reason: > See [evaluation.md](evaluation.md) for the original scoring. ``` 4. Write the deliberation log entry to `log.md` using the **Deliberation Log Entry Template** 5. For each item listed in the "What This Decision Does NOT Solve" section of the ADR just written, create a deferred decision stub: - Slugify the concern (first ~5 words, kebab-case) - Check if `.decisions//` already exists — skip if so - Write `.decisions//adr.md` using the Step 0D deferred template: - Problem: the concern text - Why Deferred: "Scoped out during `` decision. ``." - Resume When: "When `` implementation is stable and this concern becomes blocking." - What Is Known So Far: "Identified during architecture evaluation of ``. See `.decisions//adr.md` for the architectural context." - Next Step: "Run `/architect ""` when ready to evaluate." - Add a row to the Deferred section of `.decisions/CLAUDE.md` - Create …(truncated)