soul-enhance

namespace	aiwg
name	soul-enhance
platforms	["all"]
description	Improve an existing SOUL.md by identifying vague sections, suggesting missing content, and generating calibration examples

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)