project-fix

Implements the 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

Role in the SDD meta-configuration flow

This skill is the equivalent of the APPLY phase of the SDD cycle, applied to project configuration:

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

The audit-report.md generated by /project-audit is the INPUT of this skill. Without that artifact, this skill cannot operate.

Absolute rule: This skill NEVER invents corrections. It only implements what is in FIX_MANIFEST from audit-report.md.

Prerequisite: audit-report.md

Before anything else, I verify that .claude/audit-report.md exists.

If it does NOT exist:

❌ .claude/audit-report.md not found

This skill requires /project-audit to have been run first.
The audit report is the specification I implement.

Please run: /project-audit

If it exists but is more than 7 days old:

⚠️ The audit-report.md is [N] days old (generated: [date])

Options:
  1. Use the existing report anyway (may be outdated)
  2. Run /project-audit first for a fresh diagnosis

How would you like to proceed?

Execution Model

project-fix operates as a stable executor with three stages:

Stage	Responsibility	Output
Manifest intake	Read and validate `audit-report.md` and its `FIX_MANIFEST`	Parsed action lists, readiness to execute
Phase execution	Apply the permitted actions in severity and phase order	Created files, modified files, skip/failure outcomes
Final reporting	Record the run and present the resulting state	`ai-context/changelog-ai.md` entry and final fix summary

The execution model is intentionally stable. Detailed handlers may evolve, but the command remains: intake, execute, report.

Action Classes

project-fix uses three action classes.

Class	Typical examples	Side effects	Confirmation model
Automatic actions	create missing files, append missing sections, add safe markers	Yes	Executed inside the approved phase flow
Guided actions	delete duplicate local skills, optional phase execution decisions	Yes	Explicit confirmation required
Informational actions	`move-to-global`, language violations, deprecated or unknown manifest items	No automatic side effects	Report only

Notes:

The class is more important than the specific handler name. Handlers are implementations of one of these three behavior types.
Informational actions may still be important, but they never acquire automatic mutation behavior just because they appear in the manifest.

Compatibility Policy

Compatibility behavior is a separate policy layer of project-fix, not an implicit side effect of individual handlers.

Compatibility rules currently include:

Stale-manifest compatibility: if an older audit report contains deprecated action types, the command preserves safety first and avoids speculative edits.
Deprecated mechanism compatibility: any action that targets .claude/commands/ is skipped because commands/ is deprecated.
Two-tier placement compatibility: move-to-global remains informational only; no automated writes to ~/.claude/skills/ are allowed.
Unknown-action compatibility: unsupported or unknown action types are downgraded to skip-or-recommendation behavior, never automatic mutation.

This policy MUST be explicit whenever compatibility behavior affects whether an action is executed.

Process

Step 1 — Read and parse the FIX_MANIFEST

I read the FIX_MANIFEST block from audit-report.md. I extract:

required_actions.critical[]
required_actions.high[]
required_actions.medium[]
required_actions.low[]
missing_global_skills[]
orphaned_changes[]
violations[]
skill_quality_actions[] (Dimension 9 — may be absent if D9 was skipped)

I normalize the parsed items into action classes:

Automatic: safe file creation or additive update actions described by the manifest
Guided: destructive or user-choice actions that require explicit confirmation before side effects
Informational: recommendation-only, deprecated, or unknown action types that must not execute automatically

If an action type is deprecated, unsupported, or unknown:

I do NOT execute it automatically
I report it as skipped or recommendation only
I preserve the rest of the fix run

I present the user a summary of what I am going to do:

📋 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 all corrections? (critical + high + medium)
  S → Execute all recommended
  C → Critical only (minimum for functional SDD)
  R → Review one by one
  N → Cancel

I wait for the user's response before continuing.

Step 2 — Execute by phases

I process actions in order of severity. Each phase has a checkpoint.

Phase 1 — Critical Corrections (block SDD)

Mode detection (run once): Check if Engram MCP is reachable (mem_context) → if yes: active mode = engram; if no: active mode = none.

I execute in this order:

1.1 Create missing global SDD skills

type: install_skill
target: "[skill-name]"

If any global SDD skill is missing from ~/.claude/skills/, I notify the user — I cannot create them automatically, but I indicate exactly what is missing and where they should be.

1.2 Update CLAUDE.md — add SDD section

type: update_file
target: .claude/CLAUDE.md
section: sdd_section

If CLAUDE.md does not mention /sdd-*, I add this section at the end of CLAUDE.md:

## SDD — Spec-Driven Development

This project uses SDD. Artifacts are persisted to Engram.

| Command                    | Action                                      |
| -------------------------- | ------------------------------------------- |
| `/sdd-explore <topic>`     | Explore without committing to changes       |
| `/sdd-propose <change>`    | Create a change proposal                    |
| `/sdd-apply <change>`      | Implement the task plan                     |
| `/sdd-verify <change>`     | Validate implementation against specs       |
| `/sdd-status`              | View status of active changes               |

Multi-phase flows (explore → propose → spec+design → tasks, or the full cycle) are handled by the orchestrator as meta-commands — type them directly in conversation, they do not appear as skills.

**Full flow**: explore → propose → spec + design → tasks → apply → verify → archive

Checkpoint: I present the critical actions executed and ask for confirmation to continue with high-priority ones.

Phase 2 — High Corrections (degrade quality)

2.1 Create missing memory files

type: create_file
target: ai-context/[file].md
template: [stack|architecture|conventions|known-issues|changelog-ai]

For each missing file, I generate real content based on what I can detect from the project:

stack.md: I read package.json/pyproject.toml, generate dependency table with real versions
architecture.md: I read folder structure and config files, document the detected pattern
conventions.md: I read 3-5 existing code files, infer and document real conventions
known-issues.md: Start with a "Production Safety Rules" section and leave structure to be filled
changelog-ai.md: Create with initial entry documenting this fix

2.2 Update stack in CLAUDE.md

type: update_file
target: .claude/CLAUDE.md
section: tech_stack

If the declared versions do not match package.json, I update the Tech Stack table with the real values.

2.3 Fix Skills registry

type: add_registry_entry / remove_registry_entry
target: .claude/CLAUDE.md
section: skills_registry

Add to the registry the skills that are on disk but not listed
Mark as [MISSING FILE] the skills listed but without a file (do not remove them, inform)

Checkpoint: I present high-priority actions executed. I ask for confirmation to continue with medium-priority ones.

Phase 3 — Medium Corrections

3.1 Add missing sections in CLAUDE.md If sections such as Unbreakable Rules, Plan Mode Rules, Quick Reference are missing — I add the corresponding ones with content inferred from the project.

3.2 Update Folder Structure in CLAUDE.md If directories exist in .claude/ that are not documented in CLAUDE.md, I add them to the Folder Structure table.

3.3 Fix broken cross-references For broken references where the destination file does NOT exist and should: I create it with minimal content. For references where the file exists but the path is misspelled: I fix the path.

Checkpoint: I present medium-priority actions. I offer to execute low-priority ones.

Phase 4 — Low Corrections (optional, I ask first)

4.1 Install recommended global tech skills For each recommended global skill not installed locally:

Recommended skill: react-19
Available at: ~/.claude/skills/react-19/SKILL.md
To install it in this project: /skill-add react-19

I do not install automatically — I only inform with the exact command.

4.2 Notify architecture violations Violations found in Dimension 7 are NOT auto-corrected — they are code changes that require human review. I present them with context:

⚠️ Architecture violations (require manual review):
  - src/pages/api/payment.js:45 — Business logic in API route
  - src/components/Cart.jsx:23 — Direct service import (should use hook)

Phase 5 — Dimension 9 Corrections (Project Skills Quality)

5.1 Parse skill_quality_actions

Read skill_quality_actions[] from FIX_MANIFEST.

If the key is absent or the list is empty:

Skip Phase 5 silently — no output, no prompt

If actions are present, present the Phase 5 checkpoint:

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 to global catalog (manual)

Proceed with Phase 5? [Y/n]

If user declines, skip Phase 5 entirely.

5.2 delete_duplicate handler

For each action with action_type: delete_duplicate:

⚠️ Duplicate skill found:
  Local  : [local_path]
  Global : [global_counterpart]
  Detail : [detail]

Delete local copy? [y/N]

On y: delete .claude/skills/<name>/ directory recursively. Log to ai-context/changelog-ai.md.
On N: mark skipped (user declined). Continue to next action.
If directory no longer exists: mark skipped (already deleted). Continue.

5.3 add_missing_section handler

For each action with action_type: add_missing_section:

Check if the target file exists. If not: mark failed (file not found) and notify user. Continue.
Read current content of local SKILL.md.
Determine format type: parse YAML frontmatter block (content between first --- pair). Extract format: value. If absent or unrecognized → treat as procedural. This step reads the skill file at repair time; do NOT rely solely on the FIX_MANIFEST entry for the format value.
For each section in missing_sections[]:
- Check if section heading already exists (idempotency guard) — if yes: mark skipped (section already present).
- Check for <!-- AUDIT: stub added by project-fix marker — if present: mark skipped (stub already added).
- Otherwise: select stub template matching the resolved format (see table below) and append it at the end of the file.

Format-aware stub selection (authoritative contract in docs/format-types.md):

Resolved format	Missing section being added	Stub to insert
`procedural` (or absent/unknown)	`## Process`	Process stub (see below)
`reference`	`## Patterns`	Patterns stub (see below)
`anti-pattern`	`## Anti-patterns`	Anti-patterns stub (see below)
any format	`## Rules`	Rules stub (see below)
any format	`Triggers`	Triggers stub (see below)

Stub templates:

For missing ## Rules:

<!-- AUDIT: stub added by project-fix [YYYY-MM-DD] — fill in before using this skill -->

## Rules

> Scaffold note: replace this text with the concrete constraints and invariants for this skill.

For missing ## Process (format: procedural or absent):

<!-- AUDIT: stub added by project-fix [YYYY-MM-DD] -->

## Process

> Scaffold note: replace this text with the real step-by-step process instructions.

For missing ## Patterns (format: reference):

<!-- AUDIT: stub added by project-fix [YYYY-MM-DD] -->

## Patterns

> Scaffold note: replace this text with the core patterns and examples for this technology or library.

For missing ## Anti-patterns (format: anti-pattern):

<!-- AUDIT: stub added by project-fix [YYYY-MM-DD] -->

## Anti-patterns

> Scaffold note: replace this text with the anti-patterns to avoid and their corrections.

For missing **Triggers**:

<!-- AUDIT: stub added by project-fix [YYYY-MM-DD] -->

**Triggers**: Replace this scaffold text with the slash command and natural-language triggers for this skill.

Log each modification to ai-context/changelog-ai.md.

5.4 flag_irrelevant handler

For each action with action_type: flag_irrelevant:

Read current content of local SKILL.md.
Check if <!-- AUDIT: skill may be irrelevant is already the first line — if yes: mark skipped (already flagged).
Otherwise: prepend the following comment block as the first line of the file:

<!-- AUDIT: skill may be irrelevant to current project stack. Review and delete if unused. Added by project-fix [YYYY-MM-DD] -->

Log to ai-context/changelog-ai.md.

flag_language handler

For each action with action_type: flag_language:

Report to user:

ℹ️ Language violation in: [local_path]
Detail: [detail]
Action required: translate content to English manually.
This file has NOT been modified.

Log the finding to ai-context/changelog-ai.md.
Do NOT modify the SKILL.md file.

move-to-global handler

Before listing individual skills, print the following note once per fix run (not once per skill):

ℹ️ Two-tier skill model reminder:
   .claude/skills/ is project-local (versioned in repo — team-visible).
   ~/.claude/skills/ is machine-global (available across all projects but not present for collaborators who clone).

For each action with disposition move-to-global:

ℹ️ Manual action required — [local_path]
This skill may be a candidate for promotion to the global catalog.

To promote manually:
  1. Copy: cp [local_path] ~/.claude/skills/[skill_name]/SKILL.md
  2. Register in agent-config repo: skills/[skill_name]/SKILL.md
  3. Run install.sh to deploy
  4. Run /skill-add [skill_name] in the original project to add a registry reference
  5. Delete the local copy after verifying the global version works

No automated action taken.

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 — Record in changelog

When done, I add an entry to ai-context/changelog-ai.md:

## [YYYY-MM-DD] — project-fix executed

**Score before**: [XX]/100
**Actions executed**: [N] critical, [N] high, [N] medium
**Files created**: [list]
**Files modified**: [list]
**SDD Readiness**: [FULL|PARTIAL|NOT CONFIGURED] → [final state]
**Notes**: [any important decision made]

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 development with SDD: /sdd-explore <topic> or /sdd-propose <change-name>

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

Internal templates

Template: SDD section

See Step 2 — 1.2 above for the CLAUDE.md SDD section template.

Template: changelog entry

## [YYYY-MM-DD] — [description of the change]

**Type**: [Feature|Bug Fix|Refactor|Config|Documentation]
**Agent**: Claude [model]
**Modified files**:

- `path/file.ext` — [what was done]

**Decisions made**:

- [decision and its reason]

**Notes**: [anything important for future sessions]

Rules

Without audit-report.md I do not operate — I ask the user to run /project-audit first
I only implement what is in FIX_MANIFEST — I never invent additional corrections
Checkpoint between phases — I never execute the next phase without user confirmation
I do not fix production code — I report architecture violations but do not touch them
I always record in changelog — each fix is documented in ai-context/changelog-ai.md
If a file already has more complete content than the template, I do not overwrite it — I do an intelligent merge or add only the missing sections
Idempotent: running /project-fix twice on the same project must not cause duplications
When done, I always suggest: "Run /project-audit to verify the new score"
NEVER touch .claude/commands/ — commands/ is a deprecated mechanism; this skill does not create, modify, or delete files under that path. Any FIX_MANIFEST action of type fix_commands_registry or targeting .claude/commands/ MUST be skipped and noted in the output as 'skipped — commands/ is deprecated'.
Unknown or deprecated action types never gain automatic side effects — if an action cannot be mapped to a supported handler safely, it is downgraded to a skip or recommendation outcome.