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

yaml

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

yaml

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:

markdown

## 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

yaml

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

yaml

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

yaml

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]

: 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

markdown

<!-- 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):

markdown

<!-- 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):

markdown

<!-- 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):

markdown

<!-- 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**

markdown

<!-- 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:

markdown

<!-- 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

markdown

## [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

markdown

## [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.

project-fix

NPX Install

Tags

SKILL.md Content

project-fix

Role in the SDD meta-configuration flow

Prerequisite: audit-report.md

Execution Model

Action Classes

Compatibility Policy

Process

Step 1 — Read and parse the FIX_MANIFEST

Step 2 — Execute by phases

Phase 1 — Critical Corrections (block SDD)

Phase 2 — High Corrections (degrade quality)

Phase 3 — Medium Corrections

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

Phase 5 — Dimension 9 Corrections (Project Skills Quality)

Step 3 — Record in changelog

Step 4 — Final report

Internal templates

Template: SDD section

Template: changelog entry

Rules