Best-Practice Creator

Best-Practice Creator — Workflow

Use this workflow when creating a new best-practice file for the _opensquad/core/best-practices/ library.

Pre-flight Checks

1. Scan existing best-practice files: Read _opensquad/core/best-practices/_catalog.yaml. Extract id, name, whenToUse, file from each entry.
2. Check for overlap: Verify the new best-practice file doesn't duplicate an existing entry's whenToUse scope. If there's overlap, clarify the differentiation before proceeding.
3. List available skills: Read all skills/*/SKILL.md files. Extract name, description, type from each — these may inform the best-practice file's content.

Creation Checklist

For each new best-practice file, ensure ALL of the following:

Frontmatter (YAML)

• id: lowercase kebab-case (e.g., copywriting)
• name: Display name for catalog listing (e.g., "Copywriting & Persuasive Writing")
• whenToUse: Multi-line with positive scope AND "NOT for: ..." negative scope referencing other best-practice IDs
• version: "1.0.0" for new best-practice files

Body (Markdown) — All sections mandatory

• Core Principles: 6+ numbered domain-specific decision rules, each with a bold title and detailed explanation
• Techniques & Frameworks: Concrete methods, models, or processes practitioners use in this discipline (e.g., diagnostic steps, framework selections, structural patterns)
• Quality Criteria: 4+ checkable criteria as - [ ] list that can be used to evaluate output
• Output Examples: 2+ complete examples, 15+ lines each, realistic NOT template-like
• Anti-Patterns: Never Do (4+) + Always Do (3+), each with explanation
• Vocabulary Guidance: Terms/phrases to Always Use (5+), Terms/phrases to Never Use (3+), Tone Rules (2+)

Quality Minimums

Post-Creation Steps

1. Update existing best-practice files' whenToUse

For each existing best-practice file whose scope overlaps with the new one:

• Add a "NOT for: {overlapping-scope} → See {new-best-practice-id}" line to their whenToUse
• Bump their version (patch increment)

2. Update _catalog.yaml

Add a new entry to _opensquad/core/best-practices/_catalog.yaml with:

• id: matching the frontmatter id
• name: matching the frontmatter name
• whenToUse: single-line summary of the scope (positive only, no "NOT for")
• file: {id}.md

Place it under the appropriate section comment (Discipline or Platform best practices).

3. File placement

Save to _opensquad/core/best-practices/{id}.md.

4. Validation

Re-read the created file and verify:

• All checklist items above are present
• YAML frontmatter parses correctly (no syntax errors)
• whenToUse references only existing best-practice IDs
• Output examples are realistic, not template placeholders
• File exceeds 200 lines
• Corresponding entry exists in _catalog.yaml

Best-Practice Updater — Workflow

Use this workflow when updating best-practice files in the _opensquad/core/best-practices/ library.

Versioning Rules (Semver)

Always update the version field in the YAML frontmatter after any change.

Update Scenarios

When a best-practice file is removed from the library

1. Get the removed best-practice file's id
2. Remove its entry from _opensquad/core/best-practices/_catalog.yaml
3. Scan ALL remaining best-practice files in _opensquad/core/best-practices/*.md
4. For each file, check if the removed ID is referenced in whenToUse
   • Look for patterns: "NOT for: ... → See {removed-id}"
5. If found, remove that "NOT for" line
6. Bump the affected files' version (patch: x.x.X)

When a new best-practice file is added to the library

The Best-Practice Creator workflow (above) handles the initial whenToUse cross-references during creation. This section is only needed if cross-references were missed or need adjustment after the fact.

1. Read the new best-practice file's whenToUse — identify its scope
2. Scan existing best-practice files for overlapping scope
3. Add "NOT for: {new-scope} → See {new-id}" where appropriate
4. Bump affected files' version (patch)
5. Ensure the new entry exists in _catalog.yaml

When updating a best-practice file's content

1. Make the content changes
2. Verify ALL mandatory sections still exist:
   • Core Principles (6+ rules)
   • Techniques & Frameworks (3+ techniques)
   • Quality Criteria (4+ checkable items)
   • Output Examples (2+ complete examples)
   • Anti-Patterns (Never Do + Always Do)
   • Vocabulary Guidance (Always Use, Never Use, Tone Rules)
3. Bump version according to semver rules above
4. If the whenToUse scope changed, update cross-references in other best-practice files and in _catalog.yaml

When updating a best-practice file's whenToUse scope

This is the most impactful change — it affects how the Architect selects best practices during squad creation.

1. Document the old scope and new scope
2. Update the best-practice file's whenToUse field
3. Scan ALL other best-practice files' whenToUse for references to this ID
4. Update cross-references to reflect the new scope
5. Update the whenToUse summary in _catalog.yaml
6. Bump version (minor if scope expanded, patch if scope narrowed)

Validation Checklist

After ANY update, verify:

• Version was bumped correctly (patch/minor/major per rules above)
• All mandatory sections still present and non-empty
• whenToUse cross-references are consistent across ALL best-practice files
• No broken cross-references to removed best-practice IDs
• Output examples are still realistic and complete
• File still exceeds 200 lines minimum
• _catalog.yaml entry is in sync with frontmatter (id, name, whenToUse)

Bulk Operations

Verify catalog consistency

Read _opensquad/core/best-practices/_catalog.yaml
For each entry in catalog:
  1. Verify _opensquad/core/best-practices/{entry.file} exists
  2. Read the file's frontmatter
  3. Verify entry.id matches frontmatter id
  4. Verify entry.name matches frontmatter name
  5. Flag any mismatches

For each .md file in _opensquad/core/best-practices/ (excluding _catalog.yaml):
  1. Verify a corresponding entry exists in _catalog.yaml
  2. Flag any orphaned files with no catalog entry

Verify cross-reference consistency

For each best-practice file A in _opensquad/core/best-practices/*.md:
  For each "NOT for: ... → See {id}" in A.whenToUse:
    1. Verify _opensquad/core/best-practices/{id}.md exists
    2. Verify {id}'s whenToUse covers the referenced scope
    3. Flag inconsistencies