project-fix（项目修复）

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:

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.

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:

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.

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

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:

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

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

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.