fearovex/project-fix

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 format:. Absent or unrecognized → treat as procedural. Read the skill file at repair time — do NOT trust only the FIX_MANIFEST entry.
4. For each section in missing_sections[]:
   • Section heading already present → skipped (section already present).
   • <!-- AUDIT: stub added by project-fix marker present → skipped (stub already added).
   • Otherwise → append the format-matching stub from STUB_TEMPLATES.md and log changelog.

Stub selection (authoritative contract in docs/format-types.md):

| Resolved format | Missing section | Stub source | |------------------------|----------------------|---------------------------------| | procedural (default) | ## Process | Procedural Process stub | | reference | ## Patterns | Reference Patterns stub | | anti-pattern | ## Anti-patterns | Anti-pattern stub | | any | ## Rules | Rules stub | | any | **Triggers** | Triggers stub |

Checkpoint after Phase 5:

Phase 5 complete — [N] actions processed

  ✅ deleted               : [N]
  ✅ stubs added           : [N]
  ✅ flagged irrelevant    : [N]
  ℹ️ language violations   : [N] (manual fix required)
  ℹ️ move-to-global        : [N] (manual — see instructions above)
  ⏭️ skipped               : [N]
  ❌ failed                : [N]

Step 3 — Changelog entry

Append the per-fix-run changelog entry from STUB_TEMPLATES.md to ai-context/changelog-ai.md.

Step 4 — Final report

✅ Fix completed — [Project Name]

Actions executed:
  ✅ [N] critical
  ✅ [N] high
  ✅ [N] medium
  ⏭️ [N] low (informed, not auto-executed)

Files created:    [list]
Files modified:   [list]

SDD Status: [FULL / PARTIAL / NOT CONFIGURED]
  - Engram: [✅ reachable | ❌ not reachable]
  - Global SDD skills: [✅ complete | ⚠️ missing: list]
  - CLAUDE.md mentions /sdd-*: [✅ yes | ✅ added]

To verify the result:
  → /project-audit  (should show a higher score)
  → To start SDD: /sdd-explore <topic> or /sdd-propose <change-name>

Changes recorded in: ai-context/changelog-ai.md

---

Rules

1. Without audit-report.md do NOT operate — ask the user to run /project-audit first.
2. Only implement what is in FIX_MANIFEST. Never invent additional corrections.
3. Checkpoint between phases. Never execute the next phase without user confirmation.
4. Do NOT fix production code. Architecture violations are reported, never auto-modified.
5. Always record in ai-context/changelog-ai.md — each fix run is documented.
6. If the target already has content more complete than the template, do NOT overwrite — intelligent merge or add only missing sections.
7. Idempotent: running /project-fix twice on the same project must NOT cause duplications. Idempotency relies on heading detection AND the <!-- AUDIT: ... --> marker.
8. When done, always suggest: "Run /project-audit to verify the new score".
9. NEVER touch .claude/commands/. The directory is deprecated. Any FIX_MANIFEST action targeting it (e.g. fix_commands_registry) MUST be skipped with output: "skipped — commands/ is deprecated".
10. Unknown or deprecated action types never gain automatic side effects. They are downgraded to skip or recommendation outcomes.