deftai · MScottAdams · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/.agents/skills/deft-interview/SKILL.md b/.agents/skills/deft-interview/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: deft-interview
+description: >-
+  Deterministic structured Q&A interview loop. Use when any skill needs
+  structured user input through focused questions with defaults and
+  confirmation gate.
+---
+
+Read and follow: skills/deft-interview/SKILL.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -56,6 +56,7 @@ When user input matches a trigger keyword, read the corresponding skill:
 - "setup" / "bootstrap" / "onboard" → `skills/deft-setup/SKILL.md`
 - "sync" / "good morning" / "update deft" / "update vbrief" / "sync frameworks" → `skills/deft-sync/SKILL.md`
 - "pre-pr" / "quality loop" / "rwldl" / "self-review" → `skills/deft-pre-pr/SKILL.md`
+- "interview" / "ask questions" / "structured interview" → `skills/deft-interview/SKILL.md`
 
 ## Development Process (always follow)
 
@@ -68,6 +69,7 @@ When user input matches a trigger keyword, read the corresponding skill:
 
 **Before committing:**
 - Run `task check` (validate + lint + test) — this is the pre-commit gate
+- ! New source files (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`) MUST include corresponding test files in the same PR -- running existing tests alone is not sufficient for new code; forward coverage requires new tests that exercise the new code paths
 - Add CHANGELOG.md entry under `[Unreleased]`
 - Verify .github/PULL_REQUEST_TEMPLATE.md checklist items are satisfied
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **skills/deft-interview/SKILL.md -- deterministic structured Q&A interview skill** (#296, t2.11.1): Created `skills/deft-interview/SKILL.md` with RFC2119 legend and YAML frontmatter encoding a deterministic interview loop any skill can invoke -- 7 rules: one-question-per-turn, numbered options with stated default (`[default: N]`), explicit other/IDK escape option, depth gate, default-acceptance, confirmation gate, and structured handoff contract (answers map); created `.agents/skills/deft-interview/SKILL.md` thin pointer; added AGENTS.md Skill Routing entry; updated deft-setup Phase 1 and Phase 2 to reference deft-interview; added 12 tests
+- **deft-swarm Phase 6 Slack release announcement** (#292, t1.22.1): Added Step 6 to `skills/deft-swarm/SKILL.md` Phase 6 -- generates standard Slack announcement block with version, release title, summary, key changes, swarm agent count, duration, PR numbers, and GitHub release URL
+
 ### Fixed
+- **deft-swarm Phase 6 read-back verification after rebase conflict resolution** (#288, t1.21.1): Added `!` rule to Phase 6 Step 1 requiring re-read and structural integrity verification after resolving rebase conflicts and before `git add`; added `!` rule preferring `edit_files` over shell regex for CHANGELOG.md/SPECIFICATION.md; added 2 anti-patterns
+- **Strengthen test-with-code rule across 4 surfaces** (#294, t1.23.1): Added `!` rule to AGENTS.md Before committing requiring new source files to include test files; updated main.md testing gate to distinguish regression vs forward coverage; added constraint to deft-swarm Prompt Template; added forward test coverage check to deft-build pre-commit checklist
 - **Resolve 5 untracked xfail gaps in known_failures.json** (#295, t1.24.1): Flipped 20 xfail entries to passing across 5 gap categories -- (1) flipped 3 stale xfails for root PROJECT.md and core/project.md (already cleaned in prior PRs); (2) created tools/taskfile-migration.md stub to resolve broken See also link from tools/taskfile.md; (3) standardized RFC2119 legend format in 5 context/*.md files and added legend to languages/commands.md; (4) added missing shape sections to 8 files (## Commands to languages/6502-DASM.md, languages/markdown.md, languages/mermaid.md; ## Workflow to strategies/discuss.md, strategies/research.md; ## Framework Selection or ## Core Architecture to interfaces/cli.md, interfaces/rest.md, interfaces/web.md); (5) rephrased deprecated path and legacy name references in specs/testbed/SPECIFICATION.md to avoid triggering content tests
 
 ### Changed

diff --git a/SPECIFICATION.md b/SPECIFICATION.md
@@ -1055,23 +1055,33 @@ Agents on Windows writing files via PowerShell reach for [System.Text.Encoding]:
 
 Add ! rule to skills/deft-swarm/SKILL.md Phase 6 Step 1: after resolving any rebase conflict and before running git add, re-read the resolved file and verify structural integrity (no conflict markers, no collapsed lines, no encoding artifacts). Prefer edit_files over shell regex for CHANGELOG.md and SPECIFICATION.md conflict resolution. Mirrors mandatory pre-commit file review from t1.11.4, targeted at the rebase conflict resolution path. Closes #288.
 
-- <first acceptance criterion placeholder>
+- skills/deft-swarm/SKILL.md Phase 6 Step 1 contains ! rule for read-back verification after conflict resolution: re-read file, check no conflict markers, no collapsed lines, no encoding artifacts
+- skills/deft-swarm/SKILL.md Phase 6 Step 1 contains ! rule preferring edit_files over shell regex for CHANGELOG.md and SPECIFICATION.md conflict resolution
+- skills/deft-swarm/SKILL.md Anti-Patterns contains entry prohibiting git add without read-back verification
+- tests/content/test_skills.py passes
 
 **Traces**: #288
 
 ## t1.22.1: deft-swarm Phase 6 -- auto-generate Slack release announcement after swarm release (#292)  `[pending]`
 
 Add a step to skills/deft-swarm/SKILL.md Phase 6 (after creating the GitHub release) that generates a standard Slack announcement block and presents it to the user. Include version, release title, summary, key changes, swarm agent count, approximate duration, PR numbers, and GitHub release URL. Closes #292.
 
-- <first acceptance criterion placeholder>
+- skills/deft-swarm/SKILL.md Phase 6 contains Step 6: Generate Slack Release Announcement after GitHub release
+- Announcement template includes: version, release title, summary, key changes, agent count, duration, PR numbers, GitHub release URL
+- Step uses ! rules for all required fields
+- tests/content/test_skills.py passes
 
 **Traces**: #292
 
 ## t1.23.1: Strengthen test-with-code rule -- new source files must include tests (#294)  `[pending]`
 
 Strengthen the testing enforcement gate across 4 surfaces: (1) AGENTS.md Before committing: ! rule -- new source files (scripts/, src/, cmd/, *.py, *.go) MUST include corresponding test files in the same PR; running existing tests is not sufficient. (2) main.md Decision Making: update t1.6.1 testing gate to distinguish regression (existing tests pass) from forward coverage (new code has new tests). (3) deft-swarm SKILL.md prompt template CONSTRAINTS: new source files must have corresponding tests. (4) deft-build SKILL.md pre-commit checklist: for each new source file in this PR, verify a corresponding test file exists. Future deterministic gate (task verify:test-coverage) deferred to #233 Phase 5. Closes #294.
 
-- <first acceptance criterion placeholder>
+- AGENTS.md Before committing section contains ! rule: new source files MUST include corresponding test files in the same PR
+- main.md Decision Making testing gate distinguishes regression coverage (existing tests pass) from forward coverage (new code has new tests)
+- skills/deft-swarm/SKILL.md Prompt Template CONSTRAINTS contains new source files must have corresponding tests
+- skills/deft-build/SKILL.md pre-commit checklist contains forward test coverage check
+- tests/content/test_skills.py passes
 
 **Traces**: #294
 
@@ -1087,7 +1097,13 @@ Fix all 5 untracked xfail gaps in a single cleanup PR: (1) remove or replace lea
 
 Create skills/deft-interview/SKILL.md with RFC2119 legend and frontmatter encoding a deterministic interview loop any skill can invoke: one-question-per-turn rule, numbered options with stated default (e.g. [default: 3]), explicit other/IDK escape option, depth gate (! keep asking until no material ambiguity remains), default-acceptance rule (bare enter/yes/default accepts stated default), confirmation gate (display all captured answers and require yes/no before proceeding), and structured handoff contract (answers map for calling skill). Create .agents/skills/deft-interview/SKILL.md thin pointer. Update AGENTS.md Skill Routing table with trigger keywords (interview, ask questions, structured interview). Update deft-setup SKILL.md Phase 1 and Phase 2 to reference deft-interview for Q&A loops. Add tests/content/test_skills.py coverage. Anti-patterns: asking multiple questions at once, proceeding without confirmation gate, omitting defaults, omitting other escape. Closes #296.
 
-- <first acceptance criterion placeholder>
+- skills/deft-interview/SKILL.md exists with RFC2119 legend and YAML frontmatter
+- Contains 7 rules: one-question-per-turn, numbered options with stated default, other/IDK escape, depth gate, default acceptance, confirmation gate, structured handoff contract
+- Anti-patterns section covers: multiple questions, missing confirmation gate, missing defaults, missing escape option
+- .agents/skills/deft-interview/SKILL.md thin pointer exists
+- AGENTS.md Skill Routing table contains interview / ask questions / structured interview entry
+- skills/deft-setup/SKILL.md Phase 1 and Phase 2 reference deft-interview
+- tests/content/test_skills.py covers new skill with 12 tests
 
 **Traces**: #296
 

diff --git a/main.md b/main.md
@@ -49,7 +49,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 - ~ Suggest improvements even when not asked
 - ! Before implementing any planned change that touches 3+ files or has an accepted plan artifact, propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. "Confirm? yes/no") — the user must reply with an affirmative (`yes`, `confirmed`, `approve`) to satisfy this gate; a broad 'proceed', 'do it', or 'go ahead' does NOT satisfy it
 - ? For solo projects (single contributor): the `/deft:change` proposal is RECOMMENDED but not mandatory for changes fully covered by the quality gate (`task check`); it remains mandatory for cross-cutting, architectural, or high-risk changes regardless of team size
-- ! No implementation is complete until tests are written and `task check` passes — this gate applies unconditionally and a general 'proceed' instruction does not waive it
+- ! No implementation is complete until tests are written and `task check` passes — this gate applies unconditionally and a general 'proceed' instruction does not waive it. This gate has two dimensions: (a) **regression coverage** -- existing tests continue to pass, and (b) **forward coverage** -- new source files (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`) have corresponding new test files that exercise the new code paths. Running existing tests alone satisfies (a) but not (b)
 - ⊗ Commit or push directly to the default branch (master/main) — always create a feature branch and open a PR, even for single-commit changes. The only exception is if the user **explicitly** instructs a direct commit for the current task, or if `PROJECT.md` contains `Allow direct commits to master: true` under `## Branching`.
 - ⊗ Fix a discovered issue in-place mid-task without filing a GitHub issue — always file the issue and continue the current task; do not derail the active workflow to apply an instant fix (#198). **Carve-out**: if the discovered issue is a hard blocker (the current task literally cannot be completed without fixing it), fixing it in-scope is permitted, but a GitHub issue MUST be filed before or alongside the fix; nice-to-fix, quality improvements, and adjacent issues remain prohibited (#241)
 - ⊗ Continue executing a skill past its explicit instruction boundary — when a skill's steps are complete, stop and return to the calling context; do not drift into adjacent work (#198)

diff --git a/skills/deft-build/SKILL.md b/skills/deft-build/SKILL.md
@@ -140,8 +140,9 @@ See `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.
 2. ! **Unintended duplication** -- accidental double entries in CHANGELOG.md, SPECIFICATION.md, or structured data files
 3. ! **Structural issues** -- malformed CHANGELOG entries, broken table rows, mismatched index entries, invalid JSON/YAML
 4. ! **Semantic accuracy** -- verify that counts, claims, and summaries in CHANGELOG entries and ROADMAP changelog lines match the actual data in the commit (e.g. "triaged 4 issues" must match the number actually triaged, issue numbers cited must match the issues actually added)
-5. ! **Semantic contradictions** -- when adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing
+5. ! **Semantic contradictions** -- when adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing
 6. ! **Strength duplicates** -- when strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains
+7. ! **Forward test coverage** -- for each new source file in this PR (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`), verify a corresponding test file exists in the same PR; running existing tests is not sufficient for new code
 
 ⊗ Commit without re-reading all modified files first.
 

diff --git a/skills/deft-interview/SKILL.md b/skills/deft-interview/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: deft-interview
+description: >
+  Deterministic structured Q&A interview loop. Use when any skill needs to
+  gather structured input from the user through a series of focused questions
+  with numbered options, stated defaults, and a confirmation gate before
+  artifact generation.
+---
+
+# Deft Interview
+
+Deterministic interview loop that any skill can invoke to gather structured user input.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## When to Use
+
+- Another skill needs to gather structured input from the user (e.g. deft-setup Phase 1/Phase 2)
+- User says "interview", "ask questions", or "structured interview"
+- A workflow requires a series of focused questions with explicit defaults and confirmation before proceeding
+
+## Interview Loop
+
+### Rule 1: One Question Per Turn
+
+! Ask ONE focused question per step. After the user answers, send the NEXT question in a new message. Repeat until all questions for the current interview are answered.
+
+- ⊗ Include two or more questions in the same message under any circumstances
+- ⊗ List upcoming questions -- only show the current one
+- ⊗ Combine the current question with a summary of previous answers unless explicitly at the confirmation gate
+
+### Rule 2: Numbered Options with Stated Default
+
+! Every question MUST present numbered answer options. Exactly one option MUST be marked as the default using the `[default: N]` notation inline.
+
+Example:
+```
+Which deployment platform?
+1. Cross-platform (Linux / macOS / Windows)
+2. Web / Cloud [default: 2]
+3. Embedded / low-resource
+4. Other / I don't know
+```
+
+- ! The default MUST be stated inline with the option (e.g. `[default: 2]`), not in a separate line or footnote
+- ! If no option is objectively better, pick the most common choice and mark it as default
+- ~ Use structured question tools (AskQuestion, question picker, multi-choice UI) when available
+
+### Rule 3: Explicit "Other / I Don't Know" Escape
+
+! Every question MUST include an escape option. The last numbered option MUST be either:
+- "Other (please specify)" -- for open-ended alternatives
+- "I don't know" -- when the user may lack context to answer
+- "Other / I don't know" -- combined form (preferred)
+
+- ⊗ Present a question with no escape option -- the user must always have a way out
+- ~ When the user selects the escape option, follow up with a brief open-ended prompt to capture their input or acknowledge the gap
+
+### Rule 4: Depth Gate
+
+! Keep asking until no material ambiguity remains before artifact generation. The interview is NOT complete until the calling skill's required inputs are all captured with sufficient specificity to generate the target artifact.
+
+- ! If an answer introduces new ambiguity (e.g. user selects "Other" and describes something that requires follow-up), ask clarifying questions before moving on
+- ! Do not truncate the interview to save time -- completeness takes priority over brevity
+- ~ The calling skill defines what "sufficient specificity" means by providing a list of required fields in the handoff contract
+
+### Rule 5: Default Acceptance
+
+! When a question has a stated default, the user may accept it with any of the following responses:
+- Bare enter / empty response
+- "yes", "y", "ok", "default", "keep"
+- The default option number (e.g. "2")
+
+! Do NOT re-ask the question when the user accepts the default. Record the default value and proceed to the next question.
+
+- ⊗ Re-ask a question because the user's acceptance was "too brief" -- any of the listed responses is a valid acceptance
+- ⊗ Interpret an empty response as a refusal or skip
+
+### Rule 6: Confirmation Gate
+
+! After ALL questions are answered (depth gate satisfied), display a summary of ALL captured answers in a clearly formatted list and require explicit yes/no confirmation before proceeding.
+
+Format:
+```
+Here are the values I captured:
+
+- **Field 1**: value
+- **Field 2**: value
+- **Field 3**: value
+...
+
+Confirm these values? (yes / no)
+```
+
+- ! Accept only explicit affirmative responses (`yes`, `confirmed`, `approve`) -- reject vague responses (`proceed`, `do it`, `go ahead`)
+- ! If the user says `no`: ask which values to correct, re-ask those specific questions only (do not restart the full interview), then re-display the updated summary and re-confirm
+- ! If any value appears to be auto-generated filler (repeated default text, placeholder strings, or values that echo the question prompt), warn the user explicitly before confirming
+- ⊗ Proceed to artifact generation without displaying the summary and receiving explicit confirmation
+
+### Rule 7: Structured Handoff Contract
+
+! When the interview is complete (confirmation gate passed), the skill exits with an **answers map** -- a structured key-value representation of all captured answers that the calling skill uses to generate artifacts.
+
+The answers map format:
+```json
+{
+  "field_1": "captured value",
+  "field_2": "captured value",
+  "field_3": ["list", "if", "multi-select"],
+  ...
+}
+```
+
+- ! The calling skill defines the expected keys in its invocation of deft-interview
+- ! The answers map MUST contain a value for every required key defined by the calling skill
+- ! Optional keys may be omitted if the user did not provide input and no default was applicable
+- ~ The calling skill is responsible for validating the answers map against its own schema and requesting re-interview for any missing or invalid fields
+
+## Invocation Contract
+
+When a calling skill invokes deft-interview, it MUST provide:
+
+1. **Required fields**: list of field names that must be captured (the depth gate uses this to determine completeness)
+2. **Question definitions**: for each field, the question text, numbered options (if applicable), and default value
+3. **Optional fields**: list of field names that may be skipped
+
+The calling skill MAY provide:
+- **Context preamble**: a brief description of why these questions are being asked (shown to the user before the first question)
+- **Validation rules**: constraints on acceptable values for specific fields
+
+## Anti-Patterns
+
+- ⊗ Ask multiple questions in a single message -- one question per turn, always
+- ⊗ Proceed to artifact generation without the confirmation gate -- all captured answers must be displayed and explicitly confirmed
+- ⊗ Omit the default marker from any question -- every question must have a `[default: N]` option
+- ⊗ Omit the "Other / I don't know" escape from any question -- every question must have an escape option
+- ⊗ Re-ask a question after the user accepted the default -- move on immediately
+- ⊗ Skip the depth gate and generate artifacts with known ambiguity remaining
+- ⊗ Exit the interview without producing a structured answers map for the calling skill
+- ⊗ Combine interview questions with artifact generation in the same message