jmagly 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
- Load and validate the existing SOUL.md (runs soul-validate internally)
- Identify improvement targets from the validation report
- Apply enhancements category by category
- Generate companion files if missing
- 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:
- Scan the entire SOUL.md for terms used in specific ways
- Identify jargon, metaphors, and signature phrases
- 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)