@deftai/directive-content 0.55.0

package/skills/deft-directive-pre-pr/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: deft-directive-pre-pr
+description: >-
+  Iterative pre-PR quality improvement loop. Use before pushing a branch for
+  PR creation -- after completing implementation but before task check. Cycles
+  through Read-Write-Lint-Diff until a full pass produces zero changes.
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Pre-PR -- Read, Write, Lint, Diff, Loop
+
+Structured self-review loop agents run before submitting a PR. Catches inconsistencies, missing enforcement markers, incomplete acceptance criteria, scope creep, and unintended changes before they reach the reviewer.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also**: [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) | [deft-directive-build](../deft-directive-build/SKILL.md) | [RWLDL tool](../../tools/RWLDL.md)
+
+> **Formerly `deft-rwldl`** -- renamed to clearly communicate the skill's purpose (iterative pre-PR quality loop).
+
+## Branch-Protection Policy Guard
+
+! Before entering Phase 1 (Read), run the skill-level branch-policy guard documented in `scripts/policy.py` / `scripts/preflight_branch.py` (#746 / #747). Halt before any state mutation (the Phase 2 Write phase, the Phase 3 Lint phase that may touch files) when the policy is unresolvable AND no env-var bypass is active:
+
+```
+uv run python scripts/preflight_branch.py --project-root . --quiet || exit 1
+```
+
+or invoke `task verify:branch`. Pre-PR is the last gate before push, so a stale / unresolvable policy here is the highest-leverage place to catch the bug before it reaches the bot reviewer.
+
+## Deterministic Questions Contract
+
+! Every numbered-menu prompt rendered in this skill (per-finding decision menus in Phase 4 Diff, the Phase 5 Loop restart-vs-exit gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- implicit resumption is forbidden.
+
+## When to Use
+
+- ! Before pushing a branch for PR creation
+- ! After completing implementation but before the final `task check` gate
+- ~ After addressing bot reviewer findings (run one RWLDL pass before pushing the fix batch)
+- ? During mid-implementation checkpoints on large changes
+
+## Loop Phases
+
+Each iteration proceeds through all phases in order. Do NOT skip phases or reorder them.
+
+### Phase 1 -- Read
+
+! Re-read each changed file end-to-end (`git diff master --name-only` to get the list).
+
+- ! Read every changed file in full -- do not skim or skip sections
+- ! Compare each file against its scope vBRIEF acceptance criteria in `vbrief/active/`
+- ~ If changed files include `vbrief/PROJECT-DEFINITION.vbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.
+- ! 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
+- ! When strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains
+- ~ Note any inconsistencies, missing RFC2119 markers, stale cross-references, or incomplete sections
+- ~ Check that CHANGELOG.md entries match the actual changes made
+
+### Phase 2 -- Write
+
+! Fix any issues found in the Read phase.
+
+- ! Fix inconsistencies, add missing RFC2119 enforcement markers (`!`, `~`, `⊗`)
+- ! Complete any incomplete acceptance criteria or missing content
+- ! Update stale cross-references
+- ~ Improve clarity where intent is ambiguous
+- ⊗ Make changes beyond the scope of the current task -- if you notice unrelated issues, file them as ideas or future work, do not fix them now
+
+### Phase 3 -- Lint
+
+! Run `task check` and fix any failures.
+
+- ! Run `task check` (fmt + lint + typecheck + tests + coverage)
+- ! Fix all failures before proceeding to Phase 3b
+- ~ If a lint fix requires changing a file, that counts as a change for the Loop phase
+
+~ **Windows + Grok Build (#1353):** Avoid `|`, `>`, or `2>&1` in `run_terminal_command` strings -- use Python `pathlib`/`subprocess` or plain task commands instead.
+
+### Phase 3b -- Auto-Render Exports
+
+! If `vbrief/specification.vbrief.json` exists, refresh rendered exports before the diff check:
+
+- ! Run `task prd:render` if `PRD.md` already exists in the project root
+- ! Run `task spec:render` if `SPECIFICATION.md` already exists and does not contain `<!-- deft:deprecated-redirect -->`
+- ! If `plan.architecture.codeStructure`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md` changed, run `task codebase:map` and `task verify:codebase-map-fresh` so the generated orientation projection matches its canonical inputs.
+- ⊗ Create export files that don't already exist -- only refresh existing ones
+- ⊗ Hand-edit `.planning/codebase/MAP.md` to satisfy review; update canonical metadata or provider artifacts, then regenerate it
+
+### Phase 4 -- Diff
+
+! Review the full diff against the base branch for unintended changes.
+
+```
+git --no-pager diff master
+```
+
+- ! Verify no files outside the task scope were modified
+- ! Check for scope creep -- changes that go beyond the spec task acceptance criteria
+- ! Verify no debug code, TODO comments, or temporary scaffolding remains
+- ! Confirm no unintended whitespace-only changes or formatting drift
+- ! **Run `task pr:check-closing-keywords -- --pr <N>` (or pass `--body-file` / `--commits-file` for offline checking) before opening the PR; refuse to push if findings (#737)**. The lint scans both the PR body AND every commit message for closing-keyword tokens (`close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved`) followed by `#\d+` in negation / quotation / example / code-block contexts. The recurrence record is the Layer 1 / Layer 2 / Layer 3 stack: #167 (post-merge close-verify), #697 / #698 (negation-context substring match), #401 / #700 (persistent `closingIssuesReferences` link), #735 (squash body containing `DOES NOT CLOSE #734` auto-closed #734). When the lint surfaces a known-safe occurrence (e.g. test fixtures that legitimately exercise the trigger token), pass `--allow-known-false-positives <issue-numbers>` to suppress -- DO NOT silently delete the lint invocation
+- ~ Verify the diff tells a coherent story -- a reviewer reading it top-to-bottom should understand the change
+
+### Phase 5 -- Loop
+
+! Decide whether to restart or exit.
+
+- ! If ANY fixes were made in Phase 2 (Write) or Phase 3 (Lint): restart from Phase 1 (Read)
+- ~ Phase 3b auto-renders are intentional output refreshes; they do NOT trigger a loop restart
+- ! If a full Read-Write-Lint-Diff cycle produced zero changes: exit the loop
+- ~ Track iteration count -- if you exceed 3 iterations, pause and assess whether you are oscillating between competing fixes
+
+## Exit Condition
+
+! Exit when a complete Read-Write-Lint-Diff cycle produces **zero changes** -- no file edits in Write, no lint fixes in Lint, and no scope issues in Diff.
+
+After exiting:
+- ! Run `task check` one final time to confirm clean state
+- ~ The branch is now ready for push and PR creation
+
+## Anti-Patterns
+
+- ⊗ Submit a PR without running the RWLDL loop -- every PR branch should pass at least one full cycle
+- ⊗ Exit the loop after the Lint phase without completing the Diff phase -- Diff catches scope creep and unintended changes that Lint cannot detect
+- ⊗ Skip the Read phase and jump directly to Lint -- Read catches semantic issues (missing content, wrong RFC2119 markers, incomplete acceptance criteria) that linters do not check
+- ⊗ Make out-of-scope fixes during Write -- this introduces scope creep that Diff will flag, forcing another iteration
+- ⊗ Ignore the iteration count -- more than 3 iterations usually indicates oscillating fixes or an unclear spec task
+- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term
+- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)

package/skills/deft-directive-probe/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: deft-directive-probe
+description: >-
+  Adversarial plan stress-testing via relentless one-question-per-turn
+  interrogation. Use when the operator asks to run probe, /deft:run:probe, or
+  wants a plan challenged before committing to it.
+triggers:
+  - run probe
+  - /deft:run:probe
+  - probe
+  - probe my plan
+  - stress test
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Probe
+
+Stress-test a plan before committing to it — relentless interrogation until every branch of the decision tree is resolved.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+> Strategy reference: [strategies/probe.md](../../strategies/probe.md). Probe is adversarial discovery — it assumes the plan has holes and sets out to find them.
+
+## When to Use
+
+- ~ Before committing to any significant design decision or architecture choice
+- ~ When a plan has been drafted but not yet stress-tested
+- ! When the user explicitly asks to be probed or challenged on their plan
+- ? Skip when the path forward is unambiguous and small in scope
+
+## No-Artifact Guard (active until probe complete)
+
+While probe completion criteria (below) are NOT met:
+
+- ⊗ Write or update any vBRIEF file (`vbrief/proposed/`, `vbrief/active/`, plan items, narratives)
+- ⊗ Update `vbrief/plan.vbrief.json` or register probe artifacts
+- ⊗ Post GitHub completion comments, close issues, or open PRs on behalf of the probe session
+- ⊗ Produce probe output markdown files instead of the canonical vBRIEF contract
+
+! Read existing context and interrogate only — artifacts land in the Output phase after completion.
+
+## Workflow
+
+### Step 1: Establish the plan
+
+- ! Read whatever plan, design, or spec exists in the conversation context
+- ~ If no plan is in context, ask ONE question: "What's the plan you want me to probe?"
+- ~ If codebase context is relevant, explore it to answer what you can before asking
+- ⊗ Ask follow-up questions before reading available context
+
+### Step 2: Interrogate relentlessly
+
+Walk the decision tree depth-first. For each unresolved branch:
+
+- ! Ask **ONE** focused question per message
+- ! For each question, provide your recommended answer with brief reasoning
+- ! If the codebase can answer a question, explore it instead of asking the user
+- ~ Follow the thread — if an answer opens new branches, pursue them before moving on
+- ⊗ Ask multiple questions at once
+- ⊗ Present batched decision lists, numbered option menus, or multi-item checklists in a single turn
+- ⊗ Accept vague answers — push back: "What does that mean concretely?"
+- ⊗ Move to the next branch before the current one is fully resolved
+
+#### First-turn contract
+
+! The first user-facing probe turn after loading this skill MUST contain exactly **one** focused question plus your recommended answer — nothing else that asks the user to decide among multiple items.
+
+- ⊗ Open with a summary of every open branch, a decision matrix, or a list of questions
+- ⊗ Batch "here are the areas we need to cover" bullets that substitute for the single-question rule
+
+#### Question focus areas
+
+- ! **Assumptions** — "This assumes X is guaranteed — is it?"
+- ! **Edge cases** — "What happens when Y is empty / null / at the limit?"
+- ! **Dependencies** — "This requires Z to exist — what if it doesn't?"
+- ! **Failure modes** — "How does this fail? How is that surfaced to the user?"
+- ! **Scaling** — "Does this hold at 10× the expected volume?"
+- ~ **Security surface** — "Who can reach this? What's the blast radius if it's wrong?"
+- ~ **Reversibility** — "Can this decision be changed later? What's the migration cost?"
+
+### Transition criteria (probe complete)
+
+- ! All major decision branches have been resolved
+- ! No open assumptions remain
+- ~ User has acknowledged the risks of any deliberately deferred decisions
+- ~ No new branches are surfaced by the last 2–3 questions
+
+## Output (after completion only)
+
+! Before writing output artifacts, follow the [Preparatory Guard](../../strategies/artifact-guards.md#preparatory-guard-light).
+
+`{scope}` is the project name from `PROJECT-DEFINITION.vbrief.json`, or the feature/component name if probing a sub-scope. Use the same value consistently throughout the session.
+
+- ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:
+  - `LockedDecisions` — what was resolved and why
+  - `SurfacedRisks` — concerns raised, even if not fully resolved
+  - `DeferredDecisions` — explicitly acknowledged items with justification
+- ! Each entry includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
+- ! Persist significant decisions as vBRIEF narratives on the relevant plan items
+- ⊗ Write probe output to a hand-authored markdown file — use vBRIEF narratives for machine-consumable downstream work
+
+## Chaining Gate
+
+After the probe is complete and `vbrief/proposed/{scope}-probe.vbrief.json` is written:
+
+- ! Register artifacts in `./vbrief/plan.vbrief.json` (`completedStrategies`, `artifacts`)
+- ! Return to [interview.md Chaining Gate](../../strategies/interview.md#chaining-gate) when invoked from the interview flow
+- ! Locked decisions, surfaced risks, and deferred decisions MUST flow into subsequent strategies and spec generation
+- ⊗ End the session after probe without returning to the chaining gate or the invoking strategy's next-step menu
+
+**Standalone context:** If invoked from a standalone strategy menu rather than the interview chaining gate, return to the invoking strategy's menu instead.
+
+## Anti-Patterns
+
+- ⊗ Accepting "we'll figure it out later" without marking it as explicitly deferred
+- ⊗ Asking generic checklist questions instead of following the decision tree
+- ⊗ Letting vague answers pass without pushing for concrete specifics
+- ⊗ Stopping when the conversation feels comfortable — stop when no new branches emerge
+- ⊗ Writing artifacts before transition criteria are met
+
+## EXIT
+
+When probe output is written and chaining instructions are delivered, confirm: **deft-directive-probe complete -- exiting skill.** Return to the invoking strategy's chaining gate or next-step menu.