project-fix

What this skill does

# project-fix

> Implements corrections found by `/project-audit`. Reads `audit-report.md` as
> a spec and executes each required action.

**Triggers**: `/project-fix`, apply audit corrections, fix claude project, implement audit

---

## Sibling reference file

- `STUB_TEMPLATES.md` — SDD section template, skill stub templates, flag
  markers, changelog entries. Read at execution time when applying handlers.

## Role in the SDD meta-config flow

```
/project-audit  →  audit-report.md  →  /project-fix  →  /project-audit (verify)
     (spec)           (artifact)          (apply)           (verify)
```

`audit-report.md` is the INPUT. Without it this skill cannot operate.

**Absolute rule**: NEVER invent corrections. Only implement what is in
`FIX_MANIFEST`.

---

## Prerequisite

Verify `.claude/audit-report.md` exists.

| Condition           | Action                                                                 |
|---------------------|------------------------------------------------------------------------|
| File absent         | Print `"❌ .claude/audit-report.md not found — run /project-audit first"` and stop. |
| File > 7 days old   | Ask: `"⚠️ Report is [N] days old. (1) use anyway, (2) re-audit first?"` and wait. |

## Execution model

Three stages: **manifest intake** (read + validate + class), **phase execution**
(apply by severity), **final reporting** (changelog + summary).

## Action classes

| Class           | Examples                                                              | Side effects | Confirmation                       |
|-----------------|-----------------------------------------------------------------------|--------------|------------------------------------|
| Automatic       | create missing files, append sections, add markers                    | yes          | inside approved phase flow         |
| Guided          | delete duplicate local skills, optional phase decisions               | yes          | explicit confirmation required     |
| Informational   | `move-to-global`, language violations, deprecated/unknown manifest   | no           | report only                        |

Class beats handler name. Informational items never gain automatic mutation
behavior just because they appear in the manifest.

## Compatibility policy

Explicit. Current rules:
- **Stale-manifest**: older audit reports with deprecated actions → safety first, no speculative edits.
- **Deprecated mechanisms**: any action targeting `.claude/commands/` is skipped (deprecated).
- **Two-tier placement**: `move-to-global` is informational only. No automated writes to `~/.claude/skills/`.
- **Unknown actions**: downgraded to skip-or-recommendation, never automatic mutation.

---

## Process

### Step 1 — Parse the FIX_MANIFEST

Read the `FIX_MANIFEST` block from `audit-report.md`. Extract:

- `required_actions.critical[]`, `.high[]`, `.medium[]`, `.low[]`
- `missing_global_skills[]`
- `orphaned_changes[]`
- `violations[]`
- `skill_quality_actions[]` (Dimension 9 — may be absent)

Classify each item as automatic, guided, or informational per the table above.
Deprecated/unsupported/unknown action types are reported as
`skipped` or `recommendation only`. The rest of the run continues.

Present the summary:

```
📋 Fix Plan — [Project Name]
Based on audit from [date]
Current score: [XX]/100

Actions to execute:
  ❌ Critical : [N] actions
  ⚠️ High     : [N] actions
  ℹ️ Medium   : [N] actions
  💡 Low      : [N] actions (optional)

Execute corrections?
  S → All recommended (critical + high + medium)
  C → Critical only
  R → Review one by one
  N → Cancel
```

Wait for the user.

### Step 2 — Execute by phases

Phases run in severity order. Each phase ends with a checkpoint requiring
confirmation before the next.

**Mode detection** (once): call `mem_context`. Reachable → `engram` mode.
Unreachable → `none` mode.

#### Phase 1 — Critical (block SDD)

| Action | Type | Handler |
|--------|------|---------|
| 1.1 Create missing global SDD skills | `install_skill` | Notify only — cannot create automatically. List what is missing and the expected path. |
| 1.2 Add SDD section to CLAUDE.md | `update_file` `section: sdd_section` | Append the SDD section from `STUB_TEMPLATES.md`. |

**Checkpoint**: present executed criticals; ask to continue to Phase 2.

#### Phase 2 — High (degrade quality)

| Action | Type | Handler |
|--------|------|---------|
| 2.1 Create missing memory files | `create_file` `target: ai-context/[file].md` | Generate real content from project (see below). |
| 2.2 Update stack in CLAUDE.md | `update_file` `section: tech_stack` | If declared versions diverge from `package.json`, rewrite the Tech Stack table with real values. |
| 2.3 Fix Skills registry | `add_registry_entry` / `remove_registry_entry` | Add disk-only skills to registry. Mark `[MISSING FILE]` for registry-only entries (do NOT remove them). |

**Memory file generation rules (2.1):**

- `stack.md` — read `package.json`/`pyproject.toml`, output dependency table with real versions.
- `architecture.md` — read folder structure + config files; document detected pattern.
- `conventions.md` — sample 3–5 existing code files; infer and document real conventions.
- `known-issues.md` — start with `## Production Safety Rules` section; leave the rest as structured stubs.
- `changelog-ai.md` — initial entry documenting this fix run.

**Checkpoint**: present executed highs; ask to continue to Phase 3.

#### Phase 3 — Medium

| Action | Handler |
|--------|---------|
| 3.1 Add missing CLAUDE.md sections | If `Unbreakable Rules`, `Plan Mode Rules`, `Quick Reference` are missing, add with content inferred from the project. |
| 3.2 Update Folder Structure | Add `.claude/` subdirectories that exist but are not documented. |
| 3.3 Fix broken cross-references | Destination should exist → create with minimal content. Path misspelled → fix the path. |

**Checkpoint**: present executed mediums; offer Phase 4.

#### Phase 4 — Low (optional, ask first)

| Action | Handler |
|--------|---------|
| 4.1 Recommend global tech skills | List each recommended skill and the exact command: `/skill-add <name>`. Never auto-install. |
| 4.2 Notify architecture violations | List D7 violations with file:line. Never auto-fix; these are code changes requiring human review. |

#### Phase 5 — Dimension 9 (Skill Quality Actions)

Parse `skill_quality_actions[]`. Empty/absent → skip silently. Otherwise:

```
Phase 5 — Skill Quality Actions
[N] actions found in Dimension 9

Actions to process:
  [N] delete_duplicate    — local skills that duplicate a global skill
  [N] add_missing_section — local skills missing structural sections
  [N] flag_irrelevant     — skills potentially irrelevant to current stack (INFO)
  [N] flag_language       — skills with non-English content (INFO — manual fix)
  [N] move-to-global      — skills recommended for promotion (manual)

Proceed with Phase 5? [Y/n]
```

Decline → skip Phase 5 entirely.

**Phase 5 handlers:**

| `action_type` | Class | Behavior |
|---------------|-------|----------|
| `delete_duplicate` | Guided | Per skill: confirm `[y/N]`. `y` → recursive delete of `.claude/skills/<name>/`, log changelog. `N` → `skipped (user declined)`. Directory already gone → `skipped (already deleted)`. |
| `add_missing_section` | Automatic | See sub-procedure below. |
| `flag_irrelevant` | Automatic | Read file; if first line already has the marker → `skipped (already flagged)`. Otherwise prepend the marker from `STUB_TEMPLATES.md` and log changelog. |
| `flag_language` | Informational | Print: `"ℹ️ Language violation in: [path] — translate manually. File NOT modified."` Log changelog. |
| `move-to-global` | Informational | Print the two-tier reminder once per run, then per-skill manual promotion steps. No writes. |

**`add_missing_section` sub-procedure:**

1. Target file absent → `failed (file not found)`. Continue.
2. Read current content.
3. Resolve format: parse YAML frontmatter, extract `f