20 - Guide Maintenance

Purpose

This page explains how to keep the guide useful over time.

The guide should stay practical, connected, and decision-focused. It should not become a dump of every plugin opinion, every possible chain, or every unfinished idea.

Main Rule

Every addition should reduce confusion or improve decision-making.

Before adding a new page, recipe, plugin, or rule, ask:

• Will this help me make music faster?
• Will this reduce plugin decision fatigue?
• Does this connect to my actual tools?
• Does this fit my target sound?
• Is this a repeatable workflow or just a passing thought?
• Does it belong in a general guide page, a sound recipe, or the raw inventory?

If the addition does not help future decisions, leave it out or keep it as a note outside the main guide.

Page Types

Core Guide Pages

Use for broad creative process and decision rules.

Examples:

• Start Here
• Creative Method
• Songwriting and Sound Selection

These pages should answer:

• How do I think?
• What order should I make decisions in?
• How do I avoid getting stuck?

Instrument Pages

Use for general guidance by musical source.

Examples:

• Vocals
• Guitar
• Synths and Keys
• Bass
• Drums and Percussion

These pages should answer:

• What role does this instrument play?
• What sources should I use first?
• What chains make sense?
• What common problems happen?
• What related sound recipes exist?

Instrument pages should not become artist recipes. Put specific artist/style sounds in sound-recipes/.

Production Pages

Use for process, mix decisions, creative effects, repair, mastering, and technical workflow.

Examples:

• Creative Effects and Transitions
• Mix Bus and Mastering
• Repair, Cleanup, and Problem Solving

These pages should answer:

• What job am I solving?
• What order should I work in?
• What tool should I reach for first?
• What should I avoid?

Reference Pages

Use for indexes, inventories, overlap maps, and maintenance rules.

Examples:

• Sound Recipes Index
• Plugin Inventory
• Overlap and Redundancy Map
• Guide Maintenance

These pages should answer:

• What exists?
• Where is it?
• What overlaps?
• How do I keep the guide consistent?

Sound Recipes

Use for specific target sounds, artist references, production worlds, or repeatable chains.

Examples:

• Dave Gahan / Depeche Mode Vocal
• Duane Eddy / Spaghetti Western Guitar
• Lana Del Rey / Cinematic Western Guitar
• One Dove / Dubby Dream-Pop Atmosphere

Sound recipes should answer:

• What is the target?
• What source should I start with?
• What is the fast path?
• What is the produced path?
• What tools matter?
• What should I avoid?
• What variations are useful?

File Naming Rules

Paths below are relative to content/.

General Pages

Use numbered files and clear titles.

Examples:

core-guide/01-start-here.md
instruments/07-guitar.md
production/13-mix-bus-and-mastering.md
reference/15-plugin-inventory.md

Rules:

• Keep numbering consistent.
• Use lowercase file names.
• Use hyphens, not spaces.
• Use plain descriptive titles.
• Do not duplicate the heading if the file already has one.
• Remove placeholder text when filling a page.

Sound Recipe Files

Use lowercase, hyphenated file names based on the recipe title.

Examples:

sound-recipes/vocals/dave-gahan-depeche-mode-vocal.md
sound-recipes/guitar/duane-eddy-spaghetti-western-guitar.md
sound-recipes/guitar/lana-del-rey-cinematic-western-guitar.md
sound-recipes/synths-and-production/one-dove-dubby-dream-pop-atmosphere.md

Rules:

• Keep recipe names clear and stable.
• Do not silently rename planned recipes.
• If a name changes, update every connected page.
• Use Dream-Pop with a hyphen in display titles when used as a compound adjective.
• Use readable artist/style names in the title.

Linking Rules

When adding or completing a sound recipe, update all connected pages.

At minimum:

1. Add the recipe file.
2. Add or update the relevant instrument/production page under Related Sound Recipes.
3. Add the recipe to reference/14-sound-recipes-index.md.
4. Remove it from Planned: if it was previously listed there.
5. Check for spelling/name consistency.

Example:

If creating:

sound-recipes/guitar/lana-del-rey-cinematic-western-guitar.md

Also update:

instruments/07-guitar.md
reference/14-sound-recipes-index.md

If a recipe crosses categories, update every relevant page.

Example:

A dubby atmosphere recipe may belong in:

instruments/08-synths-and-keys.md
instruments/10-drums-and-percussion.md
production/11-creative-effects-and-transitions.md
reference/14-sound-recipes-index.md

Planned Recipe Rules

Planned recipe names should be treated as real commitments, not disposable notes.

Before changing a planned recipe name:

• Check whether it appears in page 14.
• Check whether it appears in an instrument or production page.
• Decide whether the new name changes the recipe meaning.
• Keep both names if they represent different recipes.

Example:

These are different recipes:

• Sound Recipe - Air / Soft Vintage Keys
• Sound Recipe - Air / Soft Vintage Synth Pad

These should both be listed if both are useful.

Sound Recipe Template

Use this structure for new recipes.

# Sound Recipe - Artist / Style Name

## Target

Describe the sound in plain language.

---

## Best Sources

List the best instrument/plugin/source choices.

---

## Fast Path

Use this when writing or moving quickly.

1. Source
2. Basic shaping
3. Main character move
4. Space/movement
5. Final check

---

## Produced Path

Use this when the part matters and deserves more detail.

1. Source choice
2. Performance or programming notes
3. EQ
4. Compression/dynamics if needed
5. Character processing
6. Space
7. Automation
8. Arrangement check

---

## Variations

- Variation 1
- Variation 2
- Variation 3

---

## Avoid

- Common mistake
- Common mistake
- Common mistake

---

## Related Pages

- Link to related instrument page
- Link to related production page if relevant

Plugin Intake Rules

New plugins should not automatically enter the main workflow.

Before adding a plugin to the decision path, answer:

• What job does it solve?
• Do I already own a tool for that job?
• Is it faster?
• Is it better?
• Is it unique?
• Does it reduce decision fatigue?
• Does it fit my target sound?
• Is it core, character, utility, special effect, or redundant?

If the plugin is owned but not important, add it only to the raw inventory.

New Plugin Intake Template

Plugin Name

Name:

Company:

Type:

Initial Role

Category:

Workflow Role:

Fuss Rating:

Priority for My Sound:

Best Uses

Best on:

Use when:

Avoid when:

Overlap Check

Overlaps with:

Does it replace anything?

Does anything I own already do this better?

Does it reduce or increase decision fatigue?

Guide Updates Needed

Add to one or more of these only if relevant:

• reference/15-plugin-inventory.md
• reference/16-overlap-and-redundancy-map.md
• Relevant instrument page
• Relevant production page
• Relevant sound recipe
• Raw inventory only

Verdict

Keep visible in plugin menu?

Role in my workflow:

One-sentence practical summary:

Rating System

Workflow Role

Fuss Rating

Priority for My Sound

Git and Commit Rules

Use Git to preserve clean checkpoints as the guide evolves.

Use a lightweight Conventional Commits format so the commit history stays readable now and still works later if this guide becomes a website.

Commit after meaningful completed units, not after every tiny edit.

Good commit points:

• Filling a new page
• Creating a new sound recipe
• Updating connected recipe links
• Adding a plugin inventory section
• Cleaning naming or structure
• Updating README/navigation
• Adding website structure or styling
• Changing build/config/deploy files

Avoid committing:

• Half-written pages
• Broken links
• Temporary placeholder text
• Unreviewed recipe name changes
• Large unrelated changes in one commit

Commit Message Format

Use this format:

type(scope): short action summary

Scope is optional:

type: short action summary

Examples:

docs(readme): update guide navigation
docs(recipes): add Lana cinematic western guitar
docs(index): update sound recipe links
docs(inventory): add raw plugin inventory
chore(maintenance): add commit rules
fix(links): correct One Dove recipe path
feat(site): add recipe navigation
style(site): add responsive layout
build(site): configure markdown rendering
deploy(github): configure GitHub Pages

Subject Line Style

Use this style for the first line of the commit message:

• Use lowercase commit types.
• Use present tense / imperative style.
• Keep it short.
• Do not end with a period.
• Use proper capitalization only for names that require it.
• Keep one logical change per commit when possible.

Good:

docs(readme): update guide navigation
docs(recipes): add Air soft vintage synth pad
feat(site): add instrument page links
fix(links): correct One Dove recipe path

Avoid:

Updated README navigation.
Added some stuff.
Fixes.
recipes: Add Air Soft Vintage Synth Pad.

Reason:

The commit subject acts like a label or changelog entry, not a sentence. Lowercase type names and no trailing period keep the history consistent and easy to scan.

Commit Types

Recommended Scopes

Use scopes to show what area changed.

Scopes are optional. Use them only when they make the commit easier to understand.

Guide Content Examples

docs(vocals): fill vocal guide
docs(guitar): add Gretsch source guide
docs(recipes): add One Dove dubby dream-pop atmosphere
docs(index): add bass and drums planned recipes
docs(inventory): add UAD raw inventory categories
docs(overlap): map synth defaults
docs(maintenance): add plugin intake rules
fix(index): correct Air recipe naming
style(markdown): normalize recipe index spacing

Website Examples

feat(site): add homepage
feat(nav): add recipe category navigation
feat(site): render Markdown guide pages
style(layout): add responsive two-column layout
style(type): refine heading scale
build(site): configure static site output
config(markdown): add Markdown processing rules
deploy(github): configure GitHub Pages
ci(github): add link check workflow

Suggested Push Rhythm

Push after a group of safe commits.

Good times to push:

• After finishing a guide section
• After adding several recipes and connected links
• After updating README/reference pages
• Before making major restructuring changes
• Before starting website conversion work
• After a website feature works locally

Rule:

Commit locally for checkpoints. Push to GitHub when the current state is coherent.

Maintenance Checklist

Use this after any significant edit.

If Adding a New General Page

• Remove placeholder text.
• Do not repeat the heading.
• Keep the title and file number consistent.
• Add links only where useful.
• Avoid dumping unrelated plugin lists into the page.

If Adding a New Sound Recipe

• Create the recipe file.
• Link it from the relevant instrument/production page.
• Add it to page 14.
• Remove it from planned lists.
• Check recipe title consistency.
• Check file name consistency.
• Add related pages at the bottom of the recipe.

If Adding a New Plugin

• Add it to raw inventory if owned.
• Add it to decision tables only if it should affect workflow.
• Add it to overlap map only if it creates meaningful overlap.
• Add it to instrument/production pages only if it is a realistic reach-for tool.
• Do not make sale purchases look like core tools automatically.

If Renaming a Recipe

• Update page 14.
• Update all related instrument pages.
• Update all related production pages.
• Update the file name if needed.
• Update internal links.
• Check whether the old and new names actually describe different recipes.

Link Checking

Cross-links are the backbone of the guide, so keep them honest.

Run the link checker after editing links, renaming files, or adding recipes:

python3 scripts/check-links.py

It validates every relative Markdown link (and #anchor) and exits non-zero on any broken link. The same check runs automatically on push and pull requests via the link-check GitHub Action (.github/workflows/link-check.yml).

If it reports a broken link, fix the path or anchor before committing — do not commit broken links.

Recipe Checking

The link checker proves links resolve; the recipe checker proves every recipe is well-formed and fully connected.

Run it after adding or renaming a recipe:

python3 scripts/check-recipes.py

For every file under sound-recipes/ it verifies:

1. The file has a # Sound Recipe - ... H1 title.
2. The recipe is listed in reference/14-sound-recipes-index.md.
3. The recipe is linked from at least one guide page outside the index and outside sound-recipes/ (an instrument, production, core, or reference page) — i.e. the linking rules above were actually followed.

It also prints non-fatal warnings for recipes missing a Related Pages or Practical Summary section. It exits non-zero on any structural or linking error, and runs in the same GitHub Action as the link checker.

Anti-Bloat Rules

Do not add content just because it is true.

Add content only if it helps future decisions.

Avoid:

• Long theoretical explanations
• Lists of every possible plugin
• Duplicate advice across many pages
• Unstable planned names
• Artist recipes inside general instrument pages
• Tool comparisons without a decision rule
• New plugins without an overlap check
• Chains that require too many choices

Rule:

The guide should make the next session easier, not larger.