@jamie-tam/forge 6.0.0

package/skills/support-skill-validator/references/validation-checks.md

@@ -0,0 +1,280 @@
+# The five validation checks
+
+Full detail for each of the five validation checks the validator runs. Load this when actually executing a scan — the SKILL.md keeps the entry points and the severity ladder; this file keeps the procedures.
+
+---
+
+## Check 1: Directive Conflicts
+
+**Purpose:** Find contradictions between imperative statements across skills and rules.
+
+**Process:**
+
+1. **Extract Directives**
+   - Scan all SKILL.md, rules, and commands for imperative statements
+   - Target keywords: `MUST`, `NEVER`, `ALWAYS`, `NO`, `REQUIRED`, `MANDATORY`, `FORBIDDEN`, `DO NOT`
+   - Extract the full sentence containing each directive
+   - Record: file path, line context, directive text
+
+2. **Categorize Directives by Topic**
+   - Group directives by what they govern:
+     - Testing (when to test, what to test, how to test)
+     - Code generation (when to write code, what patterns)
+     - Deployment (when to deploy, prerequisites)
+     - Review (what to review, how to review)
+     - Documentation (what to document, when)
+     - Git (branching, committing, PRs)
+     - Security (secrets, auth, validation)
+     - Process (ordering, gates, approvals)
+
+3. **Cross-Check for Contradictions**
+   - Within each topic, compare directives pairwise
+   - Flag when:
+     - One says MUST and another says NEVER for the same action
+     - One says ALWAYS and another says exception/skip for the same context
+     - Scope overlap creates ambiguity (general rule vs specific skill)
+
+4. **Output Format**
+   ```
+   CONFLICTS:
+
+   [ERROR] C-001: Testing Contradiction
+     build-tdd: "NO production code without a failing test FIRST"
+     build-scaffold: "Generate project boilerplate with initial test infrastructure"
+     Analysis: Scaffold generates code before tests exist. Is scaffold exempt from TDD?
+     Suggested Resolution: Document scaffold as a TDD-exempt bootstrap phase, or
+       require scaffold to generate failing tests first.
+
+   [WARNING] C-002: Fact-Checking Overlap
+     support-debug: "FACT-CHECK FIRST: verify the reported behavior"
+     rules/common/verification.md: "verify via context7 or websearch BEFORE proceeding"
+     Analysis: Not a contradiction, but unclear which takes precedence when both apply.
+     Suggested Resolution: Clarify that verification rule is the authority,
+       support-debug applies it specifically to bug reports.
+   ```
+
+5. **Known Acceptable Conflicts**
+   - Some conflicts are intentional (e.g., `/hotfix` explicitly skips certain gates)
+   - These must be documented as intentional exceptions
+   - If documented, report as INFO not ERROR
+   - If undocumented, report as WARNING
+
+---
+
+## Check 2: I/O Graph Integrity
+
+**Purpose:** Verify that the I/O protocol forms a valid directed acyclic graph (DAG).
+
+**Severity Baseline (READ FIRST — prevents false ERRORs):**
+
+I/O Contract is **OPTIONAL** per `references/common/skill-authoring.md`. Per that rule, fields are "Usually" required, not "Always". Apply this severity ladder when classifying any I/O finding:
+
+| Situation | Default severity |
+|---|---|
+| Skill has NO `## I/O Contract` section at all (pure methodology skill) | **INFO** — by design, do not escalate without evidence the omission breaks a workflow |
+| Skill has I/O Contract but omits one field (e.g., no `Feeds into`) | **INFO** — `Feeds into` is "Usually", not mandatory |
+| `Produces X` is declared but no skill lists `Requires X` (orphaned output) | **INFO** — asymmetric mirroring is allowed; only escalate if a real consumer is observed to fail |
+| `Requires X` is declared but NO skill produces X anywhere (broken pipeline) | **ERROR** — this genuinely breaks the workflow |
+| Cycle detected in the produces→requires graph (true deadlock) | **ERROR** |
+
+Only escalate to WARNING/ERROR when you can name the downstream skill that fails and how. "X is missing a row" is INFO; "skill Y will fail to find artifact X" is WARNING/ERROR.
+
+**Process:**
+
+1. **Build the I/O Graph**
+   - For each skill that declares I/O metadata, extract:
+     - `Requires`: what artifacts it needs as input
+     - `Produces`: what artifacts it creates as output
+     - `Feeds into`: which skills consume its output
+   - Skills WITHOUT an `## I/O Contract` section are treated as methodology-only nodes. Record their existence but do not flag the omission above INFO.
+   - Build a directed graph: skill -> produces -> consumed by -> skill
+
+2. **Check for Missing Producers**
+   - For every `Requires` entry, verify at least one skill `Produces` it
+   - Missing producer = gap in the pipeline (something needs input that nothing creates)
+   ```
+   [ERROR] IO-001: Missing Producer
+     quality-test-execution requires "test-plan.md"
+     No skill produces "test-plan.md"
+     Wait -- quality-test-plan produces this. Check naming match.
+   ```
+
+3. **Check for Orphaned Outputs**
+   - For every `Produces` entry, verify at least one skill or command references it (in `Requires`, in command flow, or in protocol body)
+   - Orphaned output = artifact created but never referenced anywhere
+   - **Default severity: INFO** (per Severity Baseline above). The artifact may be consumed by a command directly without the consumer-skill mirroring the row.
+   - Escalate to WARNING only if the artifact is named in another skill's body as required and that skill would fail without it.
+   ```
+   [INFO] IO-002: Orphaned Output (asymmetric mirroring)
+     quality-security-audit produces "security audit report"
+     deliver-deploy doesn't mirror it in `Requires`.
+     `Feeds into` is "Usually", not mandatory. No workflow break observed.
+     Action: Optional — add to deliver-deploy `Requires` if consumer-side
+     visibility matters. No fix required.
+   ```
+
+4. **Check for Skills Without I/O Contract (NOT a defect)**
+   - Some skills are pure methodology and intentionally omit `## I/O Contract` (e.g., `build-tdd` — the agent owns its TDD methodology handoff, the calling command owns the orchestration).
+   - **Default severity: INFO**. Note the omission for awareness; do not block.
+   ```
+   [INFO] IO-005: Skill Omits I/O Contract by Design
+     build-tdd has no `## I/O Contract` section.
+     Per `references/common/skill-authoring.md`, I/O Contract is OPTIONAL for
+     methodology-only skills. build-tdd's task scope and artifact paths are
+     supplied by the calling command (/feature, /bugfix, /hotfix) and by the
+     dispatched builder agent.
+     Action: None. This is intentional design.
+   ```
+
+5. **Check for Circular Dependencies**
+   - Verify the graph is acyclic
+   - Circular dependency = deadlock (A requires B's output, B requires A's output)
+   ```
+   [ERROR] IO-003: Circular Dependency
+     build-tdd requires architecture artifacts
+     plan-architecture requires codebase analysis
+     discover-codebase-analysis requires existing code
+     build-tdd produces existing code
+     Cycle: build-tdd -> plan-architecture -> discover-codebase-analysis -> build-tdd
+     Note: This is a false positive -- discover-codebase-analysis is for EXISTING
+       code, not code being built. Mark as checked.
+   ```
+
+6. **Verify Artifact Path Consistency**
+   - Check that artifact paths are consistent across skills
+   - If one skill produces `.forge/work/{type}/{name}/test-plan.md` and another requires `test-plan.md`, flag the ambiguity
+   ```
+   [WARNING] IO-004: Path Ambiguity
+     quality-test-plan produces: ".forge/work/{type}/{name}/test-plan.md"
+     quality-test-execution requires: "test plan"
+     Recommend: Use consistent path references across skills.
+   ```
+
+---
+
+## Check 3: Responsibility Overlaps
+
+**Purpose:** Flag when multiple skills claim the same responsibility.
+
+**Process:**
+
+1. **Extract Responsibility Claims**
+   - From each skill's "Process" section, extract what it does
+   - From each skill's "Covers" section, extract what it reviews
+   - From rules, extract what they enforce
+
+2. **Identify Overlaps**
+   - Multiple skills claiming to do the same thing
+   - Multiple rules enforcing the same constraint differently
+   - A skill doing something that a rule also enforces
+
+3. **Classify Overlaps**
+
+   | Type | Severity | Example |
+   |---|---|---|
+   | **Redundant enforcement** | WARNING | Both code-review and security-audit check for secrets |
+   | **Conflicting ownership** | ERROR | Both test-plan and tdd claim to write unit tests |
+   | **Layered enforcement** | INFO | Rule sets standard, skill enforces it (this is correct design) |
+
+4. **Output Format**
+   ```
+   OVERLAPS:
+
+   [WARNING] O-001: Fact-Checking Responsibility
+     Claimed by: support-debug (Phase 0), rules/common/verification.md, quality-code-review
+     Analysis: Three components all perform fact-checking.
+     Suggested Resolution: verification.md is the authority on WHEN to fact-check.
+       support-debug applies it to bug reports. quality-code-review applies it to reviews.
+       Document this hierarchy explicitly.
+
+   [INFO] O-002: Layered Security Enforcement
+     rules/common/security.md: Sets security standards
+     quality-security-audit: Enforces security standards in code review
+     quality-code-review: Checks for secret exposure in critical pass
+     Analysis: This is correct layered enforcement. No action needed.
+   ```
+
+---
+
+## Check 4: Gate Completeness
+
+**Purpose:** Verify every command transition has a defined quality gate.
+
+**Process:**
+
+1. **Extract Command Flows**
+   - Parse each command file for its skill sequence
+   - Identify every transition between skills (skill A -> skill B)
+
+2. **Check Gate Definitions**
+   - For each transition, verify a gate is defined in `references/common/quality-gates.md`
+   - Gate must specify: what is checked, pass criteria, fail action
+
+3. **Flag Missing Gates**
+   ```
+   [ERROR] G-001: Missing Gate
+     /feature command: build-tdd -> quality-code-review
+     No gate defined for this transition.
+     Recommended: Define gate criteria (e.g., "all tests pass, no lint errors").
+   ```
+
+4. **Flag Undocumented Exemptions**
+   - Some commands intentionally skip gates (e.g., `/hotfix` may skip brainstorming)
+   - These MUST be documented as intentional
+   - If a gate is skipped but not documented as intentional, flag it
+   ```
+   [WARNING] G-002: Undocumented Gate Exemption
+     /hotfix command skips gate between discover -> plan
+     This may be intentional for emergency fixes, but it is not documented.
+     Recommended: Add explicit exemption documentation: "Hotfix skips brainstorming
+       gate because emergency fixes prioritize speed over design exploration."
+   ```
+
+5. **Verify Gate Criteria Are Testable**
+   - "Code must be good" is not a testable gate
+   - "All tests pass, coverage > 80%, no critical lint errors" is testable
+   - Flag vague gate criteria
+   ```
+   [WARNING] G-003: Vague Gate Criteria
+     Gate: architecture -> implementation
+     Criteria: "Architecture artifacts reviewed"
+     Issue: "Reviewed" is subjective. Recommended: "Architecture artifacts exist,
+       contain API contracts, DB schema (if applicable), and system diagram.
+       User has approved the approach."
+   ```
+
+---
+
+## Check 5: Post-Evolve Drift
+
+**Purpose:** After modifications, verify changed skills/rules are still consistent with the rest of the system.
+
+**Process:**
+
+1. **Identify Modified Files**
+   - Compare against last known validated state
+   - Use git diff if available, or timestamp comparison
+   - Focus validation on changed files and their connections
+
+2. **Run Targeted Checks**
+   - For each modified file:
+     - Re-run Check 1 (directives) against all other files
+     - Re-run Check 2 (I/O) for connected skills only
+     - Re-run Check 3 (overlaps) for same-domain skills
+     - Re-run Check 4 (gates) for commands that reference modified skill
+
+3. **Output Format**
+   ```
+   DRIFT:
+
+   [ERROR] D-001: New Contradiction After /evolve
+     Modified: support-debug (added "ALWAYS verify with context7 before debugging")
+     Conflicts with: rules/common/verification.md ("verify when UNCERTAIN, not always")
+     Analysis: New directive is stricter than existing rule.
+     Suggested Resolution: Align language -- either debug skill says "when uncertain"
+       or verification rule says "always."
+
+   [INFO] D-002: No Drift Detected
+     Modified: deliver-deploy (updated smoke test section)
+     All checks pass against connected skills and rules.
+   ```

package/skills/support-system-guide/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: support-system-guide
+description: "Use when the user opens a fresh session, asks 'what should I run', 'where do I start', 'which command for X', 'is this a /feature or /greenfield', or describes intent without naming a command. Routes them to the right command (/feature, /greenfield, /task-force, /harden, etc.) and explains the phase model. Skip if the user has already invoked a specific command."
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+# Support: System Guide
+
+## Overview
+
+This skill governs how the forge system itself is used. It is the meta-skill that ensures all other skills are invoked correctly, commands are chosen appropriately, and the `.forge/` working directory is managed properly.
+
+**Core Principle:** Skills are mandatory when they apply, not optional suggestions. The system works only when every applicable skill is invoked every time.
+
+## Instruction Priority
+
+forge skills override default system prompt behavior, but **user instructions always take precedence**:
+
+1. **User's explicit instructions** (CLAUDE.md, direct requests) -- highest priority
+2. **forge skills** -- override default system behavior where they conflict
+3. **Default system prompt** -- lowest priority
+
+If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+
+## How to Access Skills and Agents
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you -- follow it directly. Never use the Read tool on skill files.
+
+### Dispatch Reference
+
+When command or skill files use these directives, here is what they mean:
+
+| Directive | Action |
+|---|---|
+| **REQUIRED SUB-SKILL: Use X** | You MUST call the `Skill` tool with `skill: "X"`. Do NOT act on the task without loading the skill first. |
+| **Dispatch the X subagent** | You MUST call the `Agent` tool with `subagent_type: "forge:X"`. Do NOT perform the review yourself. |
+
+**Why this matters:** Skills contain detailed process constraints (e.g., build-tdd has 500 lines of TDD discipline). The one-line summary in the command file is NOT a substitute. If you skip loading the skill, you will miss critical constraints and produce lower-quality output.
+
+**Agent dispatch ownership:** Skills own their agents. Each skill that needs an agent dispatches it as part of its process. Commands chain skills — they do not manage agent dispatch directly. When a skill says "Dispatch the **X** subagent", that is a mandatory dispatch, not a suggestion.
+
+**When dispatching agents:** Provide the task objective, scope, and success criteria in the prompt. Agents have file access and will explore the codebase for details — see `references/common/agent-coordination.md` for role-based handling (producers need review, reviewers don't).
+
+## The Rule
+
+**Invoke relevant skills BEFORE any response or action.** Even a 1% chance a skill might apply means you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you do not need to follow it.
+
+```
+User message received
+  |
+  +-- Does message match a COMMAND? --Yes--> Route to command (see Command Routing below)
+  |                                          Command invokes skills in sequence.
+  |
+  +-- No command match
+       |
+       +-- Might any SKILL apply? --Yes (even 1%)--> Invoke skill BEFORE responding
+       |
+       +-- Definitely no skill applies --> Respond normally
+```
+
+## Command Routing
+
+When the user describes what they want to do, route them to the correct command. Commands orchestrate skills into end-to-end workflows.
+
+| User Intent | Command | What It Does |
+|---|---|---|
+| "What does this project have?" / "Show me forge" / "What can I run?" | `/forge` | One-screen discovery — installed capabilities, active work, suggested next |
+| "Add a feature" / "Implement X" / "Build Y" | `/feature` | Full lifecycle: discover -> plan -> build -> quality -> deliver |
+| "New project" / "Start from scratch" / "Greenfield" | `/greenfield` | Scaffold + full lifecycle for a new project |
+| "Fix this bug" / "Something is broken" / "Error when..." | `/bugfix` | Debug -> fix -> test -> PR |
+| "Clean up" / "Refactor" / "Improve code quality" | `/refactor` | Analyze -> refactor -> review -> PR |
+| "Production is down" / "Emergency fix" / "Critical bug" | `/hotfix` | Emergency: debug -> fix -> test -> deploy (expedited gates) |
+| "Improve the skills" / "Update a skill" / "System enhancement" | `/evolve` | Self-improvement: review skills, propose changes, validate |
+| "Check consistency" / "Validate skills" / "Run validator" | `/validate` | Validate all skills/rules for contradictions and gaps |
+
+### Command vs. Direct Skill Use
+
+- **Commands** are for workflows (multi-skill, gated sequences)
+- **Direct skill invocation** is for single capabilities ("just review this code", "just generate a test plan")
+- When in doubt, suggest the command -- it provides the full quality pipeline
+
+## Skill Groups
+
+Skills are organized by function using prefix groups. Understanding the groups helps identify which skills to invoke.
+
+### Prototype-driven phases (v6)
+The default v6 SDLC runs concept → wireframe → prototype → iterate → codify. These skills are the canonical path; the `discover-` and `plan-` groups below are non-prototype fallback.
+
+| Skill | When to Use |
+|---|---|
+| `concept-slides` | Phase 1 — produce low-fidelity marp concept deck (hook + sub-concepts + journey) |
+| `build-wireframe` | Phase 2 — single-HTML annotated wireframe with click-through demos |
+| `build-prototype` | Phase 3 — scaffold the prototype (Vite/React/TS/Tailwind/Zustand etc.) |
+| `iterate-prototype` | Phase 4 — polish loop on the prototype; small tweaks driven by `pocs/.../.forge/feedback.md` |
+| `harden` | Phase 5 — codify the locked prototype into `aiwiki/architecture/`, ADRs, slice graph |
+
+### discover- (Understand) — non-prototype fallback
+Skills that gather and structure information about what needs to be built when the prototype-driven flow does not apply.
+
+| Skill | When to Use |
+|---|---|
+| `discover-requirements` | User has raw input (notes, emails, screenshots) that needs structuring |
+| `discover-codebase-analysis` | Working on existing code, need to understand what exists |
+
+### plan- (Decide) — non-prototype fallback
+Skills that determine how to approach the work when the prototype-driven flow does not apply.
+
+| Skill | When to Use |
+|---|---|
+| `plan-brainstorm` | Need to decide HOW to approach a feature (design discussion) |
+| `plan-architecture` | Need technical artifacts: API contracts, DB schema, diagrams |
+| `plan-design-system` | Frontend feature needs visual direction (theme, colors, spacing, typography) |
+| `plan-task-decompose` | Need to break work into implementable units |
+
+### build- (Implement)
+Skills that produce code and artifacts.
+
+| Skill | When to Use |
+|---|---|
+| `build-scaffold` | New project needs directory structure, tooling, Docker setup |
+| `build-tdd` | Writing code (strict RED-GREEN-REFACTOR) |
+| `build-pr-workflow` | Need branches, worktrees, or pull requests |
+
+### quality- (Verify)
+Skills that verify work meets standards.
+
+| Skill | When to Use |
+|---|---|
+| `quality-code-review` | Code needs review — orchestrates the safety → craft → reachability → gotcha-hunter chain |
+| `quality-test-plan` | Need comprehensive test strategy (all test types) |
+| `quality-test-execution` | Need to execute tests from the test plan |
+| `quality-security-audit` | Need security review (OWASP, secrets, dependencies) |
+| `quality-uiux` | Frontend work needs UX review |
+
+### deliver- (Ship)
+Skills that deliver work to users.
+
+| Skill | When to Use |
+|---|---|
+| `deliver-deploy` | All tests pass, review done, ready to ship |
+| `deliver-db-migration` | Feature needs database schema changes |
+| `deliver-onboarding` | Need to create or update newcomer documentation |
+
+### support- (Maintain)
+Skills that maintain the system and handle problems.
+
+| Skill | When to Use |
+|---|---|
+| `support-system-guide` | (This skill) How to use the system |
+| `support-debug` | Something is broken, need systematic debugging |
+| `support-gotcha` | Lesson learned that should be recorded for prevention |
+| `support-skill-validator` | Validate skills/rules for consistency |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (support-debug, plan-brainstorm) -- these determine HOW to approach the task
+2. **Implementation skills second** (build-tdd, quality-code-review) -- these guide execution
+
+**Route by mode.** Detect repo state per `rules/common/skill-selection.md`:
+- Prototype mode (path under `pocs/`, no codified architecture in `aiwiki/architecture/`): use `iterate-prototype` for tweaks; do NOT load `plan-brainstorm` or `build-tdd`.
+- Production mode (codified architecture exists, manifest's `phase_plan.codify: active` or later): use `build-tdd` for code changes; `plan-*` skills are non-prototype fallback only.
+
+Examples:
+- "Fix this bug" -> `support-debug` first, then domain-specific skills
+- "Deploy this" -> `deliver-deploy` (which checks gates from earlier skills)
+
+## Skill Types
+
+**Rigid skills** (build-tdd, support-debug): Follow exactly. Do not adapt away the discipline. These skills exist because shortcuts cause failures.
+
+**Flexible skills** (deliver-onboarding, quality-uiux): Adapt principles to context. The output format and depth should match the project.
+
+The skill itself indicates which type it is by its language. "MUST" and "NEVER" indicate rigid. "Consider" and "adapt" indicate flexible.
+
+## .forge/ Directory Management
+
+### Auto-Creation
+
+When starting any work item (via `/feature`, `/bugfix`, etc.), auto-create the directory structure:
+
+```
+.forge/
+  work/
+    {type}/                    # feature | bugfix | refactor | hotfix | greenfield
+      {name}/
+        manifest.yaml          -> Initialize from .claude/templates/manifests/{type}.yaml
+        requirements.md        -> Populated by discover-requirements (where applicable)
+        architecture/          -> Populated by plan-architecture (where applicable)
+        tasks.md               -> Populated by plan-task-decompose (where applicable)
+        test-plan.md           -> Populated by quality-test-plan (where applicable)
+        test-results.md        -> Populated by quality-test-execution (where applicable)
+```
+
+**Note on architecture/ and decisions/ placement (v6):** The `architecture/` directory under `.forge/work/{type}/{name}/` is a working draft used by the non-prototype fallback flow. In the prototype-driven flow, final architecture pages land in `aiwiki/architecture/` (written by `harden`). Decisions (ADRs) ALWAYS land in `aiwiki/decisions/`; the `.forge/work/.../decisions/` directory was retired in v6.
+
+### Manifest Initialization
+
+```yaml
+schema_version: "6"
+name: "{name}"
+type: "{type}"  # feature | bugfix | refactor | hotfix | greenfield
+description: "{what this work is for}"
+status: in-progress  # in-progress | paused | completed | escalated
+created: "{YYYY-MM-DD}"
+command: "{command}"  # the slash command that created this manifest, e.g. "feature"
+phase_plan:        # Plan-status per workflow milestone; set at preflight.
+  concept: active  # active | active-light | active-commit-only | skipped | as-discovered | complete-inline
+  wireframe: active
+  prototype: active
+  iterate: active
+  codify: active
+  production-build: active
+  deliver: active
+phases:            # Gate state per phase; mutated by skills during execution.
+  # Shape per work type — see templates/manifests/{type}.yaml.
+```
+
+Phase names in `phase_plan` are canonical per `.claude/references/common/phases.md`; full schema in `.claude/templates/manifests/v6/SCHEMA.md`. Phases are defaults, not requirements — set `phase_plan.{phase}: skipped` (or any other plan-status) at preflight to capture deviations.
+
+### Document Versioning
+
+When a skill updates an artifact in `.forge/`:
+
+1. If the artifact has been approved by the user, do NOT overwrite it silently
+2. If rework is needed, create a new version: `architecture-v2/` or note the revision in the file
+3. The manifest tracks which version is current
+4. Never delete previous versions -- they provide audit trail
+
+### Directory Hygiene
+
+- `.forge/` should be in `.gitignore` (working files, not source)
+- Exception: `manifest.yaml` may be committed for team visibility (project preference)
+- Gotchas live in `aiwiki/gotchas/` per the aiwiki typed-page model, see `aiwiki/CLAUDE.md`
+- Clean up completed feature directories only when user explicitly requests it
+
+## Red Flags -- STOP and Invoke the Skill
+
+These thoughts mean you are rationalizing skipping a skill:
+
+| Thought | Reality |
+|---|---|
+| "This is just a simple question" | Questions often lead to tasks. Check for applicable skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Skills provide process. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists for it, use it. |
+| "I remember this skill" | Skills evolve. Read the current version via Skill tool. |
+| "This doesn't count as a task" | Any action is a task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept is not the same as using the skill. Invoke it. |
+
+## User Instructions
+
+User instructions say WHAT to do, not HOW to do it. "Add X" or "Fix Y" does not mean skip the skill workflow.
+
+- "Add a payment feature" -> still use `/feature` (discover -> plan -> build -> quality -> deliver)
+- "Fix the login bug" -> still use `support-debug` (four-phase process)
+- "Deploy to production" -> still use `deliver-deploy` (full pipeline)
+
+The only exception is when the user **explicitly** says to skip a skill or step: "Skip brainstorming, just implement it." Even then, note what was skipped in the manifest.
+
+## Session Start Behavior
+
+When a new session begins:
+
+1. **Check for in-progress work**
+   - Walk `.forge/work/*/` for any manifests with `status: in-progress` or `status: paused`
+   - Skip `status: completed` and `status: escalated` items — they are terminal states
+   - If found, summarize: "You have in-progress work: {type}/{name}, currently in {phase}. Want to continue?"
+   - When multiple in-progress items exist, use `{type}/{name}` as the canonical identifier (names can collide across types)
+
+2. **Lightweight validation**
+   - Run `support-skill-validator` quick check (I/O graph only)
+   - Report any issues found
+
+3. **Check for recent gotchas**
+   - Read `aiwiki/gotchas/` for entries relevant to current work (and `~/.claude/gotchas/` for global entries)
+   - If a gotcha's frontmatter has a `proposed_rule:` block, surface it as a hard-interrupt per `support-gotcha` Step 6
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | -- (meta-skill, always available) |
+| **Produces** | Guidance, `.forge/` directory structure, command routing |
+| **Feeds into** | All other skills (by ensuring they are invoked correctly) |
+
+## Quick Reference
+
+| Situation | Action |
+|---|---|
+| User wants to build something | Route to `/feature` or `/greenfield` |
+| Something is broken | Route to `/bugfix` or invoke `support-debug` |
+| Code needs review | Invoke `quality-code-review` |
+| Ready to deploy | Invoke `deliver-deploy` |
+| New session, existing feature | Resume from last phase in manifest |
+| Not sure which skill | Check this guide's Skill Groups table |
+| User says "skip X" | Note in manifest, proceed without that step |
+| Thought: "skill is overkill" | STOP. Invoke the skill. |