preflight-validation

What this skill does

# Preflight Validation

Multi-layer environment validation at session start with auto-remediation. Eliminates environment configuration errors by checking git identity, branch state, toolchain availability, and integration health before any work begins.

## Contextd Integration

If contextd MCP is available:
- `memory_search` to find past preflight failures for this project
- `memory_record` to store preflight results for cross-session comparison
- `remediation_search` to find known fixes for detected issues

If contextd is NOT available:
- Validation runs inline (still works)
- No persistence of preflight results
- No cross-session comparison available

---

## When to Use

- At the start of every new session
- Before beginning any task
- When encountering environment errors (missing tools, auth failures, wrong branch)
- After switching projects or worktrees
- When a command fails unexpectedly due to environment issues

---

## Validation Tiers

Run tiers in order. Each tier gates the next -- do not proceed to T1 until T0 passes, and do not proceed to T2 until T1 passes.

### T0 - Hard Gates (Deterministic, Fast)

These checks are non-negotiable. Failures here block all work.

| Check | Command | Pass Criteria | Failure Action |
|-------|---------|---------------|----------------|
| Git identity (name) | `git config user.name` | Non-empty string | Prompt user, run `git config user.name "<value>"` |
| Git identity (email) | `git config user.email` | Non-empty string | Prompt user, run `git config user.email "<value>"` |
| Current branch | `git branch --show-current` | Not `main` or `master` | Warn, suggest creating feature branch |
| Git state clean | `git status --porcelain` | No merge conflicts | Block if merge conflict or rebase in progress |
| Merge conflict check | Look for `MERGE_HEAD`, `REBASE_HEAD` | Neither exists | Instruct user to resolve before proceeding |

**T0 Auto-Remediation:**

- **Missing git identity:** Use `AskUserQuestion` to prompt for name and email, then run:
  ```
  git config user.name "<provided name>"
  git config user.email "<provided email>"
  ```
- **On protected branch (main/master):** Suggest branch name based on task context:
  ```
  git checkout -b feat/<task-description>
  ```
  Use `AskUserQuestion` to confirm branch name before creating.
- **Merge conflict / rebase in progress:** Do NOT auto-remediate. Inform user of state and wait for manual resolution.

### T1 - Context Gates (Project Inspection)

These checks adapt to the detected project type.

| Check | Detection Method | Pass Criteria | Failure Action |
|-------|-----------------|---------------|----------------|
| Project type | Check for `go.mod`, `package.json`, `Cargo.toml`, `pyproject.toml`, `Gemfile` | At least one detected | Warn: unknown project type, proceed with generic checks |
| Go toolchain | `go version` | Exits 0, version reported | Provide install guidance |
| Go formatter | `which gofmt` | Found in PATH | Included with Go toolchain |
| gitleaks | `which gitleaks` | Found in PATH | Suggest: `brew install gitleaks` or `go install github.com/gitleaks/gitleaks/v8/cmd/gitleaks@latest` |
| Node runtime | `node --version` | Exits 0 (Node projects only) | Suggest: `brew install node` or use nvm |
| Package manager | `which npm` or `which bun` or `which pnpm` | At least one found (Node projects only) | Suggest install for detected lock file type |
| Rust toolchain | `rustc --version` | Exits 0 (Rust projects only) | Suggest: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
| Uncommitted changes | `git status --porcelain` | Empty or warn | Warn with file count, do NOT block |

**T1 Project Type Detection:**

| File Present | Project Type | Required Tools |
|-------------|-------------|----------------|
| `go.mod` | Go | `go`, `gofmt`, `gitleaks` |
| `package.json` | Node/JS/TS | `node`, `npm`/`bun`/`pnpm`, `gitleaks` |
| `Cargo.toml` | Rust | `rustc`, `cargo`, `gitleaks` |
| `pyproject.toml` or `requirements.txt` | Python | `python3`, `pip`/`uv`, `gitleaks` |
| `Gemfile` | Ruby | `ruby`, `bundler`, `gitleaks` |
| None detected | Generic | `gitleaks` |

**T1 Auto-Remediation:**

- **Missing tool:** Provide platform-appropriate install command. Do NOT auto-install without user confirmation.
- **Uncommitted changes:** Warn with summary (e.g., "3 modified, 1 untracked"). Suggest stashing if starting unrelated work.

### T2 - Integration Gates (External Checks)

These checks verify external service connectivity. Failures here are warnings, not blockers.

| Check | Command | Pass Criteria | Failure Action |
|-------|---------|---------------|----------------|
| GitHub CLI auth | `gh auth status` | Authenticated | Suggest: `gh auth login` |
| GitHub CLI available | `which gh` | Found in PATH | Suggest: `brew install gh` |
| contextd MCP | Check if contextd tools are available | Tools respond | Note: contextd unavailable, proceeding without memory |
| Docker (if needed) | `docker info` | Daemon running | Warn if project has Dockerfile/docker-compose |

**T2 Auto-Remediation:**

- **GitHub CLI not authenticated:** Suggest `gh auth login` and wait for user.
- **GitHub CLI missing:** Suggest `brew install gh` (macOS) or platform-appropriate install.
- **contextd unavailable:** Note in output. No action needed -- all skills have contextd fallbacks.
- **Docker not running:** Warn only if project contains Dockerfile or docker-compose.yml.

---

## Output Format

Present results as a table after all tiers complete:

```
## Preflight Check Results

| Check | Status | Action |
|-------|--------|--------|
| Git identity | PASS | dahendel <[email protected]> |
| Branch | WARN | On main - create feature branch? |
| Git state | PASS | Clean, no conflicts |
| Project type | PASS | Go (go.mod detected) |
| Go toolchain | PASS | go1.23.4 |
| gofmt | PASS | Available |
| gitleaks | PASS | v8.22.0 |
| Uncommitted changes | WARN | 2 modified files |
| GitHub CLI | PASS | Authenticated as dahendel |
| contextd | PASS | Available |
```

**Status values:**

| Status | Meaning | Visual |
|--------|---------|--------|
| PASS | Check passed | No action needed |
| WARN | Non-blocking issue | Action suggested but not required |
| FAIL | Blocking issue | Must resolve before proceeding |
| SKIP | Check not applicable | Project type doesn't require this |

---

## Contextd Recording

When contextd is available, record preflight results:

```
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Preflight validation: <date>",
  content: JSON.stringify({
    date: "<ISO date>",
    tiers: {
      t0: { status: "pass|fail", checks: [...] },
      t1: { status: "pass|warn", checks: [...] },
      t2: { status: "pass|warn", checks: [...] }
    },
    project_type: "<detected type>",
    remediations_applied: ["<list of auto-fixes>"],
    warnings: ["<list of warnings>"]
  }),
  outcome: "success",
  tags: ["preflight-validation", "<project-type>"]
)
```

Search for past failures before running checks:

```
mcp__contextd__memory_search(
  project_id: "<project>",
  query: "preflight-validation failure",
  tags: ["preflight-validation"],
  limit: 3
)
```

If past failures found, proactively check those specific items first.

---

## Integration with Other Skills

| Skill | Integration Point |
|-------|-------------------|
| `complexity-assessment` | Preflight runs before complexity assessment to ensure environment is ready |
| `intent-confirmation` | Preflight runs before intent preview to ensure branch and tools are valid |
| `git-repo-standards` | Branch naming validation aligns with git-repo-standards conventions |
| `git-workflows` | Branch protection awareness (main/master detection) |

---

## Mandatory Checklist

**EVERY preflight validation MUST complete ALL steps:**

- [ ] Check git identity (user.name and user.email)
- [ ] Check current branch (warn if on main/master)
- [ ] Check git state (no merge conflicts, no rebase in progress)
- [ ] Dete