jmagly/soul-enhance

soul-enhance

Improve an existing SOUL.md by identifying vague sections, suggesting missing content, and generating calibration examples.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "improve the soul" → soul quality enhancement
• "soul needs work" → soul refinement trigger

Behavior

When triggered, this skill analyzes an existing SOUL.md and makes targeted improvements. It does not rewrite the file from scratch — it preserves the author's intent while strengthening weak areas.

Enhancement Process

1. Load and validate the existing SOUL.md (runs soul-validate internally)
2. Identify improvement targets from the validation report
3. Apply enhancements category by category
4. Generate companion files if missing
5. Report changes with before/after comparisons

Enhancement Categories

1. Vague Statement Resolution

Scans for language patterns that are too generic to be useful:

| Vague Pattern | Enhancement Approach | |--------------|---------------------| | "I have nuanced views on X" | Ask: "What specifically do you believe about X?" | | "I value quality" | Ask: "What does quality mean to you? What would you sacrifice for it?" | | "I'm experienced with Y" | Ask: "How many years? What specifically have you built?" | | "I believe in best practices" | Ask: "Which practices? Which 'best practices' do you think are wrong?" | | "I'm passionate about Z" | Replace with concrete opinions about Z |

For each vague statement:

• Prompt the user with a sharpening question
• If interactive, wait for response and incorporate
• If non-interactive, suggest 2-3 specific alternatives based on context

2. Missing Section Generation

For each missing recommended section, generate a draft:

| Missing Section | Generation Strategy | |----------------|-------------------| | Standards | Propose a bar-for-completion paragraph + dangling-thread examples + complete-vs-fast resolution. Infer from opinions and pet peeves about quality, shipping, and "good enough." Surface as a draft for the author to confirm. | | Boundaries | Infer from opinions — strong opinions imply boundaries | | Tensions | Find contradictions between stated opinions | | Vocabulary | Extract signature terms from existing text | | Pet Peeves | Infer from boundaries and strong opinions | | Influences | Ask user or leave as TODO |

3. Opinion Strengthening

Opinions must be specific enough to be falsifiable:

Before: "I think testing is important"
After:  "Integration tests catch more real bugs than unit tests.
         80% coverage with real calls beats 95% with mocked everything."

For each opinion:

• Check: could someone disagree with this?
• Check: is this specific to this persona or generic?
• If too generic, strengthen with specifics from the existing worldview

4. Vocabulary Extraction

If the vocabulary section is empty or category-level:

1. Scan the entire SOUL.md for terms used in specific ways
2. Identify jargon, metaphors, and signature phrases
3. Add definitions that show personal meaning, not dictionary meaning

Before:
## Vocabulary
- Technical terms

After:
## Vocabulary
- **Blast radius**: How many things break when this thing breaks — my primary metric for evaluating changes
- **Yak shaving**: Work that's 3+ steps removed from the actual goal — I kill yak-shaving sessions aggressively
- **Accidental complexity**: Complexity from our tools and choices, not the problem domain — most complexity I encounter is accidental

5. Calibration Example Generation

Generate examples/good-outputs.md and examples/bad-outputs.md from the soul definition:

good-outputs.md: 3-5 examples of text that correctly embodies the soul

• Match tone, vocabulary, opinions
• Cover different domains mentioned in the soul
• Include the contradictions/tensions

bad-outputs.md: 3-5 anti-examples showing what the soul would NOT produce

• Generic text that could come from anyone
• Text that contradicts stated opinions
• Text that uses avoided vocabulary
• Text that breaks stated boundaries

6. Context Budget Optimization

If the soul file exceeds recommended limits:

• Identify sections that could be more concise
• Suggest moving detailed examples to companion files
• Flag redundancies between sections
• Recommend a target token count per section

Parameters

| Flag | Description | |------|-------------| | --interactive | Ask sharpening questions for each vague statement | | --sections <list> | Only enhance specific sections: --sections "opinions,vocabulary" | | --generate-examples | Force generation of calibration examples | | --dry-run | Show proposed changes without applying them |

Output

Interactive Mode

Enhancing SOUL.md...

Found 3 vague statements:

1. Line 14: "I value clean code"
   → What does "clean" mean to you specifically?
   → What would you sacrifice for clean code? What wouldn't you?
   User: "Clean means I can read it at 3 AM. I'll sacrifice DRY for readability."
   ✓ Updated: "Clean code is code I can read at 3 AM during an incident.
     I'll sacrifice DRY for readability — duplicated clarity beats obscure abstractions."

2. Line 31: "I have experience with many frameworks"
   → Which frameworks? What did each teach you?
   User: "Rails taught me convention, React taught me composition, Django taught me batteries-included"
   ✓ Updated: "I've built production systems in Rails (conventions),
     React (composition), and Django (batteries-included)."

3. Line 45: "I'm interested in distributed systems"
   → What specifically? Consensus? Networking? Data replication?
   User: "Consensus algorithms and failure modes"
   ✓ Updated: "I've spent a decade thinking about consensus algorithms
     and the creative ways distributed systems fail."

Missing sections generated:
  + Boundaries (5 items inferred from opinions)
  + Tensions (3 contradictions identified)

Calibration examples:
  + examples/good-outputs.md (4 examples)
  + examples/bad-outputs.md (3 anti-examples)

Score: 5/10 → 8/10

Non-Interactive Mode

Enhancing SOUL.md...

Changes applied:
  ~ Line 14: Strengthened vague opinion (2 alternatives provided, chose first)
  ~ Line 31: Replaced generic statement with specific alternative
  ~ Line 45: Sharpened interest description
  + Boundaries section (5 items)
  + Tensions section (3 contradictions)
  + examples/good-outputs.md (4 examples)
  + examples/bad-outputs.md (3 anti-examples)

Score: 5/10 → 8/10

Review changes with: git diff SOUL.md

Integration

With soul-validate

soul-enhance runs soul-validate internally as its first step. The validation report drives which enhancements are applied.

With soul-enable

After enhancement, if soul enforcement is already enabled, the improved SOUL.md is automatically active at the next session — no re-enabling needed.

With voice-create

If a voice profile exists, soul-enhance cross-references it to ensure consistency. If the soul file mentions vocabulary that conflicts with the voice profile's avoid-list, it flags the conflict.

Examples

# Full enhancement (interactive)
/soul-enhance --interactive

# Enhance specific sections only
/soul-enhance --sections "opinions,vocabulary,boundaries"

# Generate calibration examples without other changes
/soul-enhance --generate-examples

# Preview changes without applying
/soul-enhance --dry-run

# Enhance an agent soul file
/soul-enhance .claude/agents/test-engineer.soul.md

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/soul-validate/SKILL.md — Validation (used internally)
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/soul-create/SKILL.md — Creation skill
• @$AIWG_ROOT/docs/soul-md-guide.md — Integration guide
• #437 — SOUL.md compatibility issue (Phase 2)