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.

Execution model

Three stages: manifest intake (read + validate + class), phase execution (apply by severity), final reporting (changelog + summary).

Action classes

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)

Checkpoint: present executed criticals; ask to continue to Phase 2.

Phase 2 — High (degrade quality)

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

Checkpoint: present executed mediums; offer Phase 4.

Phase 4 — Low (optional, ask first)

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:

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

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.

project-fix — Stub Templates

Reference file consumed by SKILL.md Phase 5.3 (add_missing_section

handler) and the SDD section template referenced from Phase 1.2. Each

stub includes an HTML marker so the same section is never added twice.

SDD section (CLAUDE.md, Phase 1.2)

Inserted at the end of CLAUDE.md when the file does not mention /sdd-*.

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

Skill section stubs (Phase 5.3)

Each stub is appended to the target SKILL.md after the idempotency guard (check for existing heading + check for the AUDIT marker).

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.

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.

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.

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.

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.

flag_irrelevant marker (Phase 5.4)

Prepended as the first line of the target SKILL.md when the skill may be irrelevant to the current stack.

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

Changelog entry (Step 3)

Appended to ai-context/changelog-ai.md after every fix run.

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

Generic changelog template (when triggered outside the regular fix flow)

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