codeforge-dev 1.8.0 → 1.10.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-check/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: spec-check
+description: >-
+  This skill should be used when the user asks to "check spec status",
+  "audit specs", "which specs are stale", "spec health", "find missing
+  specs", "review spec quality", or needs a comprehensive audit of all
+  specifications in the project.
+version: 0.1.0
+context: fork
+agent: explorer
+---
+
+# Spec Health Audit
+
+Audit all specifications in the current project and report their health status.
+
+## Workflow
+
+### Step 1: Discover Specs
+
+```
+Glob: .specs/**/*.md
+```
+
+If `.specs/` does not exist, report: "No specification directory found. Use `/spec-new` to create your first spec."
+
+Exclude non-spec files:
+- `ROADMAP.md`
+- `BACKLOG.md`
+- `LESSONS_LEARNED.md`
+- Files in `archive/`
+- `_overview.md` files (report them separately as parent specs)
+
+### Step 2: Read Each Spec
+
+For each spec file, extract:
+- **Feature name** from the `# Feature: [Name]` header
+- **Version** from the `**Version:**` field
+- **Status** from the `**Status:**` field
+- **Last Updated** from the `**Last Updated:**` field
+- **Approval** from the `**Approval:**` field (default `draft` if missing)
+- **Line count** (wc -l)
+- **Sections present** — check for each required section header
+- **Acceptance criteria** — count total, count checked `[x]`
+- **Requirements** — count total, count `[assumed]`, count `[user-approved]`
+- **Discrepancies** — check if section has content
+
+### Step 3: Flag Issues
+
+For each spec, check these conditions:
+
+| Issue | Condition | Severity |
+|-------|-----------|----------|
+| **Unapproved** | Approval is `draft` or missing | High |
+| **Assumed requirements** | Has requirements tagged `[assumed]` | Medium |
+| **Stale** | Status is `planned` but Last Updated is >30 days ago | High |
+| **Incomplete** | Missing required sections (Intent, Acceptance Criteria, Key Files, Requirements, Out of Scope) | High |
+| **Long spec** | Exceeds ~200 lines — consider splitting | Info |
+| **No criteria** | Acceptance Criteria section is empty or has no checkboxes | High |
+| **Open discrepancies** | Discrepancies section has content | Medium |
+| **Missing as-built** | Status is `implemented` but Implementation Notes is empty | Medium |
+| **Stale paths** | Key Files references paths that don't exist | Low |
+| **Draft + implemented** | Status is `implemented` but Approval is `draft` — approval gate was bypassed | High |
+| **Inconsistent approval** | Approval is `user-approved` but spec has `[assumed]` requirements | High |
+
+### Step 4: Report
+
+Output a summary table:
+
+```
+## Spec Health Report
+
+| Feature | Version | Status | Approval | Updated | Lines | Issues |
+|---------|---------|--------|----------|---------|-------|--------|
+| Session History | v0.2.0 | implemented | user-approved | 2026-02-08 | 74 | None |
+| Auth Flow | v0.3.0 | planned | draft | 2026-01-15 | 45 | Unapproved, Stale (26 days) |
+| Settings Page | v0.2.0 | partial | draft | 2026-02-05 | 210 | Unapproved, Long spec |
+
+## Issues Found
+
+### High Priority
+- **Auth Flow** (`.specs/v0.3.0/auth-flow.md`): Status is `planned` but last updated 26 days ago. Either implementation is stalled or the spec needs an as-built update.
+
+### Medium Priority
+- **Settings Page** (`.specs/v0.2.0/settings-page.md`): 210 lines — consider splitting into sub-specs for easier consumption.
+
+### Suggested Actions
+1. Run `/spec-refine auth-flow` to validate assumptions and get user approval
+2. Run `/spec-update auth-flow` to update the auth flow spec
+3. Split settings-page.md into sub-specs
+
+### Approval Summary
+- **User-approved:** 1 spec
+- **Draft (needs /spec-refine):** 2 specs
+- **Assumed requirements across all specs:** 8
+```
+
+If no issues are found, report: "All specs healthy. N specs across M versions. All user-approved."

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: spec-init
+description: >-
+  This skill should be used when the user asks to "initialize specs",
+  "set up specs", "bootstrap specs", "start using specs", "create spec
+  directory", "init specs for this project", or needs to set up the
+  .specs/ directory structure for a project that doesn't have one yet.
+version: 0.1.0
+---
+
+# Initialize Specification Directory
+
+## Mental Model
+
+Before any spec can be created, the project needs a `.specs/` directory with its supporting files: a ROADMAP (what each version delivers) and a BACKLOG (deferred items). This skill bootstraps that structure so `/spec-new` has a home.
+
+---
+
+## Workflow
+
+### Step 1: Check Existing State
+
+```
+Glob: .specs/**/*.md
+```
+
+**If `.specs/` already exists:**
+- Report current state: how many specs, versions, whether ROADMAP.md and BACKLOG.md exist
+- Suggest `/spec-check` to audit health instead
+- Do NOT recreate or overwrite anything
+- Stop here
+
+**If `.specs/` does not exist:** proceed to Step 2.
+
+### Step 2: Create Directory Structure
+
+Create the `.specs/` directory at the project root.
+
+### Step 3: Create ROADMAP.md
+
+Write `.specs/ROADMAP.md` using the template from `references/roadmap-template.md`.
+
+### Step 4: Create BACKLOG.md
+
+Write `.specs/BACKLOG.md` using the template from `references/backlog-template.md`.
+
+### Step 5: Retroactive Documentation
+
+Ask the user:
+
+> "Are there existing features in this project that should be documented retroactively? I can help create specs for them using `/spec-new`."
+
+If yes, guide the user through creating a spec for each feature using `/spec-new`.
+
+If no, proceed to Step 6.
+
+### Step 6: Report
+
+Summarize what was created:
+
+```
+## Spec Directory Initialized
+
+Created:
+- `.specs/` directory
+- `.specs/ROADMAP.md` — version tracking table
+- `.specs/BACKLOG.md` — deferred items list
+
+Next steps:
+- Add features to `BACKLOG.md` with priority grades (P0–P3)
+- Pull features into a version in `ROADMAP.md` when ready to scope
+- Use `/spec-new <feature-name> <version>` to create a spec
+- Use `/spec-refine <feature-name>` to validate before implementation
+- After implementing, use `/spec-update` to close the loop
+- Use `/spec-check` to audit spec health at any time
+```
+
+---
+
+## Constraints
+
+- **Never overwrite** an existing `.specs/` directory or its contents.
+- Templates are starting points — the user will extend them as the project grows.
+
+---
+
+## Ambiguity Policy
+
+- If the user runs this in a workspace root with multiple projects, ask which project to initialize.
+- If `.specs/` exists but is missing ROADMAP.md or BACKLOG.md, offer to create only the missing files.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/roadmap-template.md` | Starter ROADMAP with version table format |
+| `references/backlog-template.md` | Starter BACKLOG with item format |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/backlog-template.md

@@ -0,0 +1,23 @@
+# Backlog
+
+Priority-graded feature and infrastructure backlog. Items are pulled into versions when ready to scope and spec. See `ROADMAP.md` for the versioning workflow.
+
+## P0 — High Priority
+
+- [ ] [Feature] — [Description]
+
+## P1 — Important
+
+- [ ] [Feature] — [Description]
+
+## P2 — Desired
+
+- [ ] [Feature] — [Description]
+
+## P3 — Nice to Have
+
+- [ ] [Feature] — [Description]
+
+## Infrastructure & CI
+
+- [ ] [Item] — [Description]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/roadmap-template.md

@@ -0,0 +1,33 @@
+# Roadmap
+
+> Features live in the priority-graded backlog until pulled into a version.
+> Versions are scoped and spec'd when ready to build — not pre-assigned.
+> See `BACKLOG.md` for the feature backlog.
+
+## How Versioning Works
+
+1. **Backlog** — All desired features live in `BACKLOG.md`, graded by priority.
+2. **Version scoping** — When ready to start a new version, pull features from the backlog.
+3. **Spec first** — Each feature in a version gets a spec before implementation begins.
+4. **Ship** — Version is done when all its specs are implemented and verified.
+
+Only the **next version** is defined in detail. Everything else is backlog.
+
+## Released
+
+_None yet._
+
+## Current
+
+### v0.1.0 — [Name] 🔧
+
+- [ ] [Feature pulled from backlog]
+- [ ] [Feature pulled from backlog]
+
+## Next
+
+> Scoped from `BACKLOG.md` when current version is complete.
+
+## Out of Scope
+
+- [Items explicitly not planned]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: spec-new
+description: >-
+  This skill should be used when the user asks to "create a spec",
+  "new feature spec", "write a spec for", "spec this feature",
+  "start a new spec", "plan a feature", or needs to create a new
+  specification file from the standard template.
+version: 0.1.0
+---
+
+# Create New Feature Specification
+
+## Mental Model
+
+A specification is a contract between the person requesting a feature and the person building it. Writing the spec BEFORE implementation forces you to think through edge cases, acceptance criteria, and scope boundaries while changes are cheap — before any code exists.
+
+Every project uses `.specs/` as the specification directory. Specs are version-organized, independently loadable, and should aim for ~200 lines.
+
+---
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Extract the feature name and version from `$ARGUMENTS`:
+- **Feature name**: kebab-case identifier (e.g., `session-history`, `auth-flow`)
+- **Version**: semver string (e.g., `v0.3.0`)
+
+If arguments are missing, ask the user for:
+1. Feature name (what is being built)
+2. Target version (which release this belongs to)
+
+**Note:** Features should be pulled from the project's backlog (`BACKLOG.md`) into a version before creating a spec. If the feature isn't in the backlog yet, add it first, then assign it to a version.
+
+### Step 2: Determine File Path
+
+- **Multi-feature version** (directory already exists or multiple features planned):
+  `.specs/{version}/{feature-name}.md`
+- **Single-feature version** (one spec covers the whole version):
+  `.specs/{version}.md`
+
+If `.specs/` does not exist at the project root, create it.
+
+If `.specs/{version}/` does not exist and you're using the directory form, create it.
+
+### Step 3: Create the Spec File
+
+Write the file using the standard template from `references/template.md`.
+
+Pre-fill:
+- **Version**: from arguments
+- **Status**: `planned`
+- **Last Updated**: today's date (YYYY-MM-DD)
+- **Approval**: `draft`
+- **Feature name**: from arguments
+
+Leave all other sections as placeholders for the user to fill.
+
+### Step 4: Guide Content Creation
+
+After creating the file, guide the user through filling it out:
+
+1. **Intent** — What problem does this solve? Who has this problem? (2-3 sentences)
+2. **Acceptance Criteria** — Use the `specification-writing` skill for EARS format and Given/When/Then patterns
+3. **Key Files** — Glob the codebase to identify existing files relevant to this feature
+4. **Schema / Data Model** — Reference file paths only, never inline schemas
+5. **API Endpoints** — Table format: Method | Path | Description
+6. **Requirements** — EARS format, numbered FR-1, FR-2, NFR-1, etc. Tag all requirements `[assumed]` at creation time — they become `[user-approved]` only after explicit user validation via `/spec-refine`.
+7. **Dependencies** — What this feature depends on
+8. **Out of Scope** — Explicit non-goals to prevent scope creep
+9. **Resolved Questions** — Leave empty at creation; populated by `/spec-refine`
+
+### Step 5: Validate
+
+Before finishing:
+- [ ] If the file exceeds ~200 lines, consider splitting into sub-specs
+- [ ] No source code, SQL, or type definitions reproduced inline
+- [ ] Status is `planned` and Approval is `draft`
+- [ ] All required sections present (even if some are "N/A" or "TBD")
+- [ ] Acceptance criteria are testable
+- [ ] All requirements are tagged `[assumed]`
+
+After validation, inform the user: **"This spec MUST go through `/spec-refine` before implementation begins.** All requirements are marked `[assumed]` until explicitly validated."
+
+The `/spec-refine` skill walks through every `[assumed]` requirement with the user, validates tech decisions and scope boundaries, and upgrades approved items to `[user-approved]`. The spec's `**Approval:**` becomes `user-approved` only after all requirements pass review.
+
+---
+
+## Sizing Guidelines
+
+- **Aim for ~200 lines per spec.** If a feature needs more, consider splitting into sub-specs with a parent `_overview.md` linking them.
+- **Reference, don't reproduce.** Write `see src/engine/db/migrations/002.sql lines 48-70` — never paste the SQL.
+- **Independently loadable.** Each spec file must be useful without loading any other file.
+- **EARS format for requirements.** Use the `specification-writing` skill for templates and examples.
+
+---
+
+## Ambiguity Policy
+
+- If the user doesn't specify a version, ask — do not assume.
+- If the feature scope is unclear, write a minimal spec with `## Open Questions` listing what needs clarification.
+- If a spec already exists for this feature, inform the user and suggest `/spec-update` instead.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/template.md` | Full standard template with field descriptions and examples |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/references/template.md

@@ -0,0 +1,129 @@
+# Specification Template
+
+Standard template for all feature specifications. Copy this structure when creating a new spec.
+
+---
+
+## Template
+
+```markdown
+# Feature: [Name]
+
+**Version:** v0.X.0
+**Status:** planned
+**Last Updated:** YYYY-MM-DD
+**Approval:** draft
+
+## Intent
+
+[What problem does this solve? Who has this problem? What's the cost of not solving it? 2-3 sentences.]
+
+## Acceptance Criteria
+
+[Testable criteria. Use Given/When/Then for complex flows, checklists for simple features, or tables for business rules. Every criterion must be verifiable.]
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Key Files
+
+[File paths most relevant to implementation — paths an implementer should read first.]
+
+**Backend:**
+- `src/path/to/file.py` — [brief description]
+
+**Frontend:**
+- `src/web/path/to/component.svelte` — [brief description]
+
+**Tests:**
+- `tests/path/to/test_file.py` — [brief description]
+
+## Schema / Data Model
+
+[Reference migration files and model files by path. Describe what changes — do NOT paste DDL, Pydantic models, or TypeScript interfaces.]
+
+- New table: `table_name` — see `src/db/migrations/NNN.sql`
+- Modified: `existing_table` — added `column_name` column
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/resource` | List resources with pagination |
+| POST | `/api/resource` | Create a new resource |
+
+## Requirements
+
+### Functional Requirements
+
+- FR-1 [assumed]: [EARS format requirement — see specification-writing skill for templates]
+- FR-2 [assumed]: When [event], the system shall [action].
+- FR-3 [assumed]: If [unwanted condition], then the system shall [action].
+
+### Non-Functional Requirements
+
+- NFR-1 [assumed]: The system shall respond to [endpoint] within [N]ms at the [percentile] percentile.
+- NFR-2 [assumed]: [Security, accessibility, scalability requirement]
+
+## Dependencies
+
+- [External system, library, or feature this depends on]
+- [Blocked by: feature X must ship first]
+
+## Out of Scope
+
+- [Explicit non-goal 1 — prevents scope creep]
+- [Explicit non-goal 2]
+
+## Resolved Questions
+
+[Decisions explicitly approved by the user via `/spec-refine`. Each entry: decision topic, chosen option, date, brief rationale.]
+
+## Implementation Notes
+
+[Post-implementation only. Leave empty in planned specs. After building, document what actually shipped vs. what was planned.]
+
+## Discrepancies
+
+[Post-implementation only. Document gaps between spec intent and actual build. Prevents next session from re-planning decided work.]
+```
+
+---
+
+## Field Descriptions
+
+| Section | Required | When to Fill |
+|---------|----------|-------------|
+| Intent | Always | At creation |
+| Acceptance Criteria | Always | At creation |
+| Key Files | Always | At creation (update post-implementation) |
+| Schema / Data Model | If applicable | At creation |
+| API Endpoints | If applicable | At creation |
+| Requirements | Always | At creation |
+| Dependencies | If applicable | At creation |
+| Out of Scope | Always | At creation |
+| Implementation Notes | Post-implementation | After building |
+| Discrepancies | Post-implementation | After building |
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `planned` | Spec written, implementation not started |
+| `partial` | Some acceptance criteria implemented, work ongoing |
+| `implemented` | All acceptance criteria met, as-built notes complete |
+
+## Approval Workflow
+
+| Tag | Meaning |
+|-----|---------|
+| `[assumed]` | Requirement was drafted by AI or inferred — treated as a hypothesis |
+| `[user-approved]` | Requirement was explicitly reviewed and approved by the user via `/spec-refine` |
+
+| Approval Status | Meaning |
+|-----------------|---------|
+| `draft` | Spec has unvalidated assumptions — NOT approved for implementation |
+| `user-approved` | All requirements are `[user-approved]` — ready for implementation |
+
+**Workflow:** `/spec-new` creates → `/spec-refine` validates → implementation begins → `/spec-update` closes the loop.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-refine/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: spec-refine
+description: >-
+  This skill should be used when the user asks to "refine a spec",
+  "review spec assumptions", "validate spec decisions", "question the
+  spec", "iterate on the spec", "check spec for assumptions", "approve
+  the spec", "walk me through the spec", or needs iterative
+  user-driven refinement of a specification through structured
+  questioning rounds.
+version: 0.1.0
+---
+
+# Iterative Spec Refinement
+
+## Mental Model
+
+A draft spec is a hypothesis, not a commitment. Every requirement, tech decision, and scope boundary in a draft is an assumption until the user explicitly validates it. This skill systematically mines a spec for unvalidated assumptions, presents each to the user for review via structured questions, and iterates until every decision has explicit user approval.
+
+No implementation begins on a spec with `**Approval:** draft`. This skill is the gate.
+
+---
+
+## Workflow
+
+### Step 1: Load & Inventory
+
+Find the target spec:
+- If `$ARGUMENTS` contains a path or feature name, use it directly
+- Otherwise, glob `.specs/**/*.md` and ask the user which spec to refine
+
+Read the full spec. Catalog:
+- Every section and whether it has content
+- The `**Approval:**` status (should be `draft`)
+- All requirements and their current markers (`[assumed]` vs `[user-approved]`)
+- The `## Open Questions` section (if any)
+- The `## Resolved Questions` section (if any)
+
+If the spec is already `**Approval:** user-approved` and all requirements are `[user-approved]`, report this and ask if the user wants to re-review anyway.
+
+### Step 2: Assumption Mining
+
+Scan each section systematically for unvalidated decisions. Look for:
+
+| Category | What to look for |
+|----------|-----------------|
+| **Tech decisions** | Database choices, auth mechanisms, API formats, libraries, protocols |
+| **Scope boundaries** | What's included/excluded without stated rationale |
+| **Performance targets** | Numbers (response times, limits, thresholds) that were assumed |
+| **Architecture choices** | Where logic lives, service boundaries, data flow patterns |
+| **Behavioral defaults** | Error handling, retry logic, fallback behavior, timeout values |
+| **Unstated dependencies** | Systems, services, or libraries the spec assumes exist |
+| **Security assumptions** | Auth requirements, data sensitivity, access control patterns |
+
+For each assumption found, prepare a question with 2-4 alternatives including the current assumption.
+
+Present findings via `AskUserQuestion` in rounds of 1-4 questions. Group related assumptions together. Example:
+
+```
+Question: "Which authentication mechanism should this feature use?"
+Options:
+- JWT with refresh tokens (current assumption)
+- Session cookies with httpOnly flag
+- OAuth2 with external provider
+```
+
+Record each answer. After the user responds, check: did any answer reveal new assumptions or contradictions? If yes, add follow-up questions to the queue.
+
+### Step 3: Requirement Validation
+
+Walk through every requirement tagged `[assumed]`:
+
+1. **Read the requirement** aloud to the user (via the question text)
+2. **Assess** — is it specific? testable? complete?
+3. **Present via AskUserQuestion** with options:
+   - Approve as-is
+   - Needs revision (user provides direction via "Other")
+   - Remove (not needed)
+   - Defer to Open Questions (not decidable yet)
+
+Process requirements in batches of 1-4 per question round. Prioritize:
+- Requirements with the most ambiguity first
+- Requirements that other requirements depend on
+- Requirements involving tech decisions or external systems
+
+For approved requirements, update the marker from `[assumed]` to `[user-approved]`.
+For revised requirements, rewrite per user direction and mark `[user-approved]`.
+For removed requirements, delete them.
+For deferred requirements, move to `## Open Questions`.
+
+### Step 4: Acceptance Criteria Review
+
+For each acceptance criterion:
+1. Is it measurable and testable?
+2. Does it map to a specific requirement?
+3. Are there requirements without corresponding criteria?
+
+Present gaps to the user:
+- Missing criteria for existing requirements
+- Criteria that don't map to any requirement
+- Criteria with vague or unmeasurable outcomes
+
+Get approval on each criterion or batch of related criteria.
+
+### Step 5: Scope & Dependency Audit
+
+Review the spec from four perspectives:
+
+**User perspective:**
+- Does the feature solve the stated problem?
+- Are there user needs not addressed?
+- Is the scope too broad or too narrow?
+
+**Developer perspective:**
+- Is this implementable with the current architecture?
+- Are the key files accurate?
+- Are there missing technical constraints?
+
+**Security perspective:**
+- Are there data sensitivity issues?
+- Is authentication/authorization addressed?
+- Are there input validation gaps?
+
+**Operations perspective:**
+- Deployment considerations?
+- Monitoring and observability needs?
+- Rollback strategy needed?
+
+Surface any missing items via `AskUserQuestion`. Get explicit decisions on scope boundaries and dependency completeness.
+
+### Step 6: Final Approval
+
+1. Present a summary of all changes made during refinement:
+   - Assumptions resolved (count)
+   - Requirements approved/revised/removed
+   - New criteria added
+   - Scope changes
+
+2. Ask for final approval via `AskUserQuestion`:
+   - "Approve spec — all decisions validated, ready for implementation"
+   - "More refinement needed — specific concerns remain"
+
+3. On approval:
+   - Set `**Approval:** user-approved`
+   - Update `**Last Updated:**` to today
+   - Verify all requirements are tagged `[user-approved]`
+   - Populate `## Resolved Questions` with the decision trail from this session
+
+4. On "more refinement needed":
+   - Ask what concerns remain
+   - Loop back to the relevant phase
+
+---
+
+## Convergence Rules
+
+- After each phase, check: did answers from this phase raise new questions? If yes, run another questioning round before advancing.
+- The skill does NOT terminate until ALL of:
+  - Every `[assumed]` requirement is resolved (approved, revised, removed, or deferred)
+  - All acceptance criteria are reviewed
+  - The user gives explicit final approval
+- If the user wants to stop early, leave `**Approval:** draft` and note remaining items in `## Open Questions`.
+
+---
+
+## Resolved Questions Format
+
+Each resolved question follows this format:
+
+```markdown
+1. **[Decision topic]** — [Chosen option] (user-approved, YYYY-MM-DD)
+   - Options considered: [list]
+   - Rationale: [brief user reasoning or context]
+```
+
+Keep entries concise — decision + options + rationale in 2-3 lines each.
+
+---
+
+## Ambiguity Policy
+
+- If the spec has no `**Approval:**` field, treat it as `draft` and add the field.
+- If requirements lack `[assumed]`/`[user-approved]` tags, treat all as `[assumed]`.
+- If the user says "approve everything" without reviewing individual items, warn that blanket approval defeats the purpose — offer to fast-track by presenting summaries of each batch.
+- If the spec is very short (< 30 lines), the full 6-phase process may be unnecessary. Adapt: merge phases 2-4 into a single review pass. Still require explicit final approval.
+- If the user provides a feature name that matches multiple specs, list them and ask which to refine.
+
+---
+
+## Anti-Patterns
+
+- **Rubber-stamping**: Presenting assumptions and immediately suggesting "approve all." Every assumption gets its own question with real alternatives.
+- **Leading questions**: "Should we use JWT as planned?" is leading. Present alternatives neutrally: "Which auth mechanism should this feature use? Options: JWT, sessions, OAuth2."
+- **Skipping phases**: Every phase surfaces different types of assumptions. Don't skip phases even if earlier phases had few findings.
+- **Silent upgrades**: Never change `[assumed]` to `[user-approved]` without presenting the item to the user first.