4. Shape Repair
Shape Repair updates note heading structure so notes match their assigned Shape templates.
Preview first:
Forge: Run Shape Repair (Dry Run)
Apply only after reviewing the preview:
Forge: Run Shape Repair
Shape Repair is intentionally conservative.
It focuses on restoring structural consistency without rewriting note content.
What Shape Repair Can Do
Shape Repair can:
- insert missing headings
- reorder headings recursively within parent sections
- preserve unknown headings
- move unmatched headings to the bottom of their section
- generate repair history and run notes
- create backups before changing notes
Repair workflows are designed to restore structure while minimizing destructive changes.
What Shape Repair Will Not Do
Shape Repair will not:
- delete headings
- delete note content
- rewrite prose
- re-level existing headings
- modify frontmatter
- fill empty sections automatically
Forge intentionally avoids aggressive content rewriting.
Shape Repair focuses on structure, not authorship.
Dry Run Workflow
Always begin with:
Forge: Run Shape Repair (Dry Run)
Dry runs preview:
- missing headings
- reordered sections
- proposed repairs
- affected notes
without modifying content.
This allows you to review structural changes safely before applying them.
Recursive Heading Repair
Shape Repair uses recursive tree matching.
Forge evaluates:
heading text + heading level + parent heading chain
This means repairs happen within the correct structural context instead of blindly moving headings around the document.
That helps avoid problems like:
- duplicated sections
- misplaced headings
- broken nesting
- incorrect hierarchy repair
Tiny tree goblin remains fully contained.
Outputs
When repairs are applied, Forge writes:
A-I/Forge/Exports/shape-repair-history.json
Forge also generates repair run notes inside the configured Shape Repair runs folder.
Typical location:
System/Exports/ShapeRepairRuns
These records help track:
- repaired notes
- repair timestamps
- repair operations
- historical structure changes
Backups and Restore
Shape Repair creates backups before modifying notes.
Recommended practices:
- use Git if possible
- keep vault backups
- review dry runs carefully
- apply repairs gradually
Shape Repair is designed to be safer than large manual structural cleanup passes, but operational caution is still recommended.
Recommended Workflow
A practical workflow usually looks like this:
- Create or refine Shapes
- Run Vault Lint
- Review Shape findings
- Run Shape Repair dry run
- Review proposed repairs
- Apply repairs gradually
- Re-run lint
Most users should avoid repairing the entire vault at once during initial rollout.
Folder-scoped repair is usually easier to validate.
Shape Repair Philosophy
Shape Repair exists to reduce long-term structural drift.
Over time, recurring note types naturally diverge:
- headings get renamed
- sections disappear
- templates evolve
- structures become inconsistent
Repair workflows help bring those notes back toward a predictable structure without destroying the content inside them.
Shapes and Downstream Workflows
Consistent note structure improves:
- Dataview dashboards
- Bases
- exports
- relationship indexes
- AI-assisted retrieval
- operational review systems
Predictable structure makes larger vaults easier to maintain and reason about over time.
