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

/project-fix

project-fix

move-to-global

• 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.

project-fix

• 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.

FIX_MANIFEST

audit-report.md

• 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)

• 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

• I do NOT execute it automatically
• I report it as

  skipped

  or

  recommendation only

• I preserve the rest of the fix run

📋 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

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

• 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

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

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)

skill_quality_actions

skill_quality_actions[]

• Skip Phase 5 silently — no output, no prompt

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]

delete_duplicate

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.

add_missing_section

action_type: add_missing_section

1. Check if the target file exists. If not: mark

   failed (file not found)

   and notify user. Continue.
2. Read current content of local

   SKILL.md

   .
3. 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.
4. 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.

docs/format-types.md

procedural

## Process

reference

## Patterns

anti-pattern

## Anti-patterns

## Rules

**Triggers**

## Rules

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

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

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

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

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.

ai-context/changelog-ai.md

flag_irrelevant

action_type: flag_irrelevant

1. Read current content of local

   SKILL.md

   .
2. Check if

   <!-- AUDIT: skill may be irrelevant

   is already the first line — if yes: mark

   skipped (already flagged)

   .
3. 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] -->

ai-context/changelog-ai.md

flag_language

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

ℹ️ 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).

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

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]

• path/file.ext

  — [what was done]

• [decision and its reason]

---

1. Without audit-report.md I do not operate — I ask the user to run

   /project-audit

   first
2. I only implement what is in FIX_MANIFEST — I never invent additional corrections
3. Checkpoint between phases — I never execute the next phase without user confirmation
4. I do not fix production code — I report architecture violations but do not touch them
5. I always record in changelog — each fix is documented in

   ai-context/changelog-ai.md

6. 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
7. Idempotent: running

   /project-fix

   twice on the same project must not cause duplications
8. When done, I always suggest: "Run

   /project-audit

   to verify the new score"
9. 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'.
10. 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.