cc-agentic-framework 1.14.1

package/framework/modules/writer/skills/writer/building-worlds/MAGIC-SYSTEMS.md

@@ -0,0 +1,311 @@
+# Magic System Design
+
+Comprehensive guide to designing magic systems, from hard to soft, incorporating Sanderson's Laws and principles from master fantasy writers.
+
+---
+
+## The Hard-Soft Spectrum
+
+Magic systems exist on a spectrum from fully explained (hard) to mysterious (soft). Neither is superior; each serves different story needs.
+
+### Hard Magic Systems
+
+**Characteristics:**
+- Clear, consistent rules readers understand
+- Specific costs and limitations
+- Magic can directly solve problems
+- Often treated like a science or technology
+
+**Strengths:**
+- Satisfying problem-solving
+- Fair play with readers
+- Enables magic-based conflict
+- Supports training/progression arcs
+
+**Weaknesses:**
+- Can feel mechanical
+- Requires extensive planning
+- Less wonder and mystery
+- Rule-breaking feels like betrayal
+
+**Examples:**
+- Allomancy (Mistborn) - Metals grant specific powers
+- Sympathy (Kingkiller) - Energy conservation laws
+- Bending (Avatar) - Element-specific abilities
+
+### Soft Magic Systems
+
+**Characteristics:**
+- Rules deliberately obscure or unstated
+- Creates atmosphere and wonder
+- Cannot reliably solve protagonist problems
+- Often tied to mystery or the divine
+
+**Strengths:**
+- Preserves sense of wonder
+- Flexible for storytelling
+- Connects to mythic/spiritual themes
+- Less front-loaded explanation
+
+**Weaknesses:**
+- Can't solve problems without feeling cheap
+- Risk of deus ex machina
+- Harder to create stakes
+- Requires discipline to avoid convenience
+
+**Examples:**
+- Gandalf's Magic (LotR) - Capabilities unknown
+- The Force (original trilogy) - Mystical, unexplained
+- Earthsea True Names - Partial rules, much mystery
+
+### Hybrid Systems
+
+**The Best of Both:**
+- Core rules are clear (hard)
+- Higher levels remain mysterious (soft)
+- Reader understands basics, marvels at mastery
+
+**Examples:**
+- Orogeny (Broken Earth) - Mechanics clear, full potential mysterious
+- Stormlight (Sanderson) - Ten Surges explained, deeper cosmere mysteries remain
+
+---
+
+## Sanderson's Laws: Deep Application
+
+### First Law: Understanding Equals Satisfaction
+
+> "An author's ability to solve conflict with magic is directly proportional to how well the reader understands said magic."
+
+**The Sliding Scale:**
+
+| Reader Understanding | Problem-Solving Allowed |
+|---------------------|------------------------|
+| Complete | Magic can be the solution |
+| Partial | Magic can assist, not solve |
+| Minimal | Magic can only complicate |
+| None | Magic creates wonder only |
+
+**Application Guide:**
+
+**Before using magic to solve a problem, ask:**
+1. Have I established this capability?
+2. Does the reader know the costs?
+3. Will this feel earned or cheap?
+
+**The Gandalf Rule:** Gandalf's magic rarely solves problems because we don't understand its limits. When he acts, it's to create obstacles (lighting pinecones) or buy time (facing Balrog), not to solve the quest.
+
+### Second Law: Limitations > Powers
+
+> "Weaknesses, limits, and costs are more interesting than powers."
+
+**The Three Types of Limitations:**
+
+#### 1. Costs (What You Pay)
+
+| Cost Type | Description | Story Effect |
+|-----------|-------------|--------------|
+| **Physical** | Exhaustion, injury, aging | Creates recovery time, vulnerability |
+| **Mental** | Sanity, memory, personality | Long-term consequences, character change |
+| **Material** | Rare components consumed | Economic stakes, scarcity plots |
+| **Social** | Reputation, relationships | Isolation, moral dilemmas |
+| **Temporal** | Time to cast, cooldowns | Tactical decisions, tension |
+| **Moral** | Ethical compromises | Character corruption arcs |
+
+#### 2. Weaknesses (What Hurts You)
+
+| Weakness Type | Example | Story Function |
+|--------------|---------|----------------|
+| **Substance** | Kryptonite | Creates vulnerability |
+| **Condition** | Sunlight kills vampires | Restricts when/where |
+| **Countermeasure** | Specific wards block magic | Creates opposition |
+| **Source Dependency** | Must touch ground | Creates tactical choices |
+
+#### 3. Scope Limits (What You Can't Do)
+
+| Limit Type | Example | Story Function |
+|------------|---------|----------------|
+| **Range** | Touch only | Forces proximity |
+| **Scale** | One person at a time | Can't solve mass problems |
+| **Target** | Only affects living things | Creates workarounds |
+| **Duration** | Effects temporary | Time pressure |
+| **Exclusion** | Can't affect self | Self-preservation stakes |
+
+**Design Exercise:** For every power, define 3 limitations before use.
+
+### Third Law: Expand Before Adding
+
+> "Before adding something new to your magic, see if you can instead expand what you already have."
+
+**The Depth Test:**
+
+Ask these before adding a new magic type:
+1. Can an existing power be combined or applied differently?
+2. Can I explore an unexplored limitation?
+3. Can I show mastery creating new applications?
+4. Will this addition complicate or clarify?
+
+**Signs You're Adding Too Much:**
+- Readers can't track capabilities
+- Powers exist for single scenes
+- No power gets deep exploration
+- Magic feels like a video game ability list
+
+**Good Expansion Examples:**
+- Basic fire magic → heating, light, steam power, metallurgy
+- Telekinesis → fine control, self-flight, kinetic shields
+- Healing → accelerating natural processes, biological knowledge
+
+---
+
+## Magic System Design Framework
+
+### Step 1: Source
+
+**Questions:**
+- Where does magic come from?
+- Is the source infinite or limited?
+- Who can access it?
+- Can access be gained or lost?
+
+**Common Sources:**
+| Source | Implications |
+|--------|--------------|
+| Innate/Genetic | Born special, chosen one tropes |
+| Learned | Anyone can study, schools/masters |
+| Divine | Tied to faith, granted by gods |
+| Environmental | Location-based, natural forces |
+| Technological | Can be mass-produced, industrialized |
+| Sacrificial | Always has cost, dark implications |
+
+### Step 2: Mechanics
+
+**Questions:**
+- How is magic activated? (Words, gestures, will, tools)
+- What determines power level?
+- How is it learned or improved?
+- What does using magic feel like?
+
+**Mechanical Choices:**
+| Aspect | Options |
+|--------|---------|
+| **Activation** | Verbal, somatic, material, mental, tool-based |
+| **Power Source** | Internal reserves, external energy, divine grant |
+| **Scaling** | Practice improves, born at fixed level, tied to sacrifice |
+| **Perception** | Visible effects, invisible, felt by sensitives |
+
+### Step 3: Costs and Limitations
+
+**Questions:**
+- What does using magic cost?
+- What can magic NOT do?
+- What circumstances prevent use?
+- What are the failure modes?
+
+**Design the failure states as carefully as success states.**
+
+### Step 4: Cultural Integration
+
+**Questions:**
+- How does society view magic users?
+- How does magic affect the economy?
+- How does magic affect warfare?
+- How does magic affect daily life?
+- What laws govern magic use?
+
+**The Second-Order Effects:**
+
+If healing magic exists:
+- What happens to medicine?
+- What happens to death?
+- Who controls access?
+- What are the economics?
+
+If teleportation exists:
+- What happens to trade routes?
+- What happens to borders?
+- What happens to crime?
+- What happens to warfare?
+
+**Every magical capability reshapes society.**
+
+---
+
+## Magic System Checklist
+
+### Core Definition
+- [ ] Source clearly defined
+- [ ] Mechanics established
+- [ ] At least 3 significant limitations
+- [ ] Cost structure meaningful
+- [ ] Failure modes described
+
+### Internal Consistency
+- [ ] Rules don't contradict
+- [ ] Costs scale with power
+- [ ] Exceptions are explained
+- [ ] Same magic works same way
+
+### Story Integration
+- [ ] Magic serves theme
+- [ ] Limitations create conflict
+- [ ] Protagonist's magic has clear constraints
+- [ ] Magic doesn't trivialize problems
+
+### Cultural Impact
+- [ ] Society reflects magic's existence
+- [ ] Economic effects considered
+- [ ] Political effects considered
+- [ ] Daily life effects considered
+
+### Reader Experience
+- [ ] Rules introduceable gradually
+- [ ] Can explain in one sentence (elevator pitch)
+- [ ] Memorable and distinctive
+- [ ] Visually/sensorily interesting
+
+---
+
+## The Rational Magic Sanity Check
+
+**Before finalizing, ask:**
+
+1. **The Conquest Question:** If this magic exists, why hasn't someone conquered the world with it?
+
+2. **The Economy Question:** If this magic exists, why do people still do [manual labor X]?
+
+3. **The Crime Question:** If this magic exists, what crimes are now possible and how are they prevented?
+
+4. **The Healing Question:** If healing magic exists, how is death still meaningful?
+
+5. **The Communication Question:** If instant communication exists, how do secrets exist?
+
+**If you can't answer these, your magic system has holes.**
+
+---
+
+## Common Pitfalls
+
+### The Power Creep Trap
+**Problem:** Each book needs bigger magic
+**Solution:** Depth, not height; explore existing magic more deeply
+
+### The Deus Ex Machina Trap
+**Problem:** New power appears to solve climax
+**Solution:** Foreshadow capabilities, pay costs established earlier
+
+### The Inconsistency Trap
+**Problem:** Magic works differently each time
+**Solution:** Document rules, review before writing magic scenes
+
+### The Video Game Trap
+**Problem:** Magic feels like ability lists
+**Solution:** Focus on fewer powers with more implications
+
+### The Meaningless Cost Trap
+**Problem:** Costs exist but never matter
+**Solution:** Force choices: using magic here means not using it there
+
+---
+
+**Next:** See [CULTURE-BUILDING.md](./CULTURE-BUILDING.md) for how magic integrates with society.

package/framework/modules/writer/skills/writer/building-worlds/REVELATION-CHECKLIST.md

@@ -0,0 +1,282 @@
+# World Revelation Checklist
+
+How to reveal your world to readers: pacing, methods, and anti-patterns.
+
+---
+
+## The Revelation Principle
+
+**You know 100% of your world. Readers should learn about 10-30%, revealed gradually.**
+
+The goal is not to communicate everything you know, but to create the feeling of a deep, real world while serving the story.
+
+---
+
+## Revelation Timing by Story Phase
+
+### First Third: Establish Mystery
+
+**Goal:** Show the world has depth. Create questions.
+
+| Technique | Example |
+|-----------|---------|
+| Partial information | References to events without explanation |
+| Contradictory accounts | Two characters remember differently |
+| Unexplained artifacts | Objects with obvious but unstated significance |
+| Hinted history | "Before the Fall..." without explaining the Fall |
+| Assumed knowledge | Characters don't explain what "everyone knows" |
+
+**Reader experience:** "This world has secrets. I want to know more."
+
+### Second Third: Connect Patterns
+
+**Goal:** Reward attention. Answer some questions. Create new ones.
+
+| Technique | Example |
+|-----------|---------|
+| Convergent information | Two sources confirm same fact |
+| Revealed connections | "The Fall" links to current conflict |
+| Deeper implications | What seemed simple is complex |
+| Perspective expansion | Enemy's viewpoint reveals hidden logic |
+| Partial answers | One mystery solved, revealing larger mystery |
+
+**Reader experience:** "Things are coming together. But there's more."
+
+### Final Third: Deliver Payoff
+
+**Goal:** Satisfy curiosity. Resolve major mysteries. Leave some for sequels.
+
+| Technique | Example |
+|-----------|---------|
+| Direct revelation | Character finally explains |
+| Assembled picture | Reader puts pieces together |
+| Climactic discovery | Plot and revelation merge |
+| Recontextualization | Known facts gain new meaning |
+| Strategic mystery preservation | Some questions remain |
+
+**Reader experience:** "That's what it all meant. But what about...?"
+
+---
+
+## Revelation Methods
+
+### Method 1: Through Character Discovery
+
+Character learns; reader learns with them.
+
+**Best for:**
+- Naive protagonists
+- Mystery-driven plots
+- Audience surrogate characters
+
+**Risk:** Info-dumping through "mentor explains"
+
+### Method 2: Through Conflict
+
+Information emerges because characters need it.
+
+**Best for:**
+- Action-heavy narratives
+- Urgent pacing
+- Avoiding exposition scenes
+
+**Risk:** Feeling forced or convenient
+
+### Method 3: Through Environment
+
+World details visible in setting.
+
+**Best for:**
+- Visual world-building
+- Subtle revelation
+- Showing not telling
+
+**Risk:** Reader missing important details
+
+### Method 4: Through Dialogue
+
+Characters discuss naturally.
+
+**Best for:**
+- Cultural information
+- Character perspectives
+- Debate and nuance
+
+**Risk:** "As you know, Bob..." syndrome
+
+### Method 5: Through Artifacts
+
+Objects tell stories.
+
+**Best for:**
+- Historical information
+- Mystery creation
+- Non-verbal revelation
+
+**Risk:** Heavy-handed symbolism
+
+---
+
+## The Information Hierarchy
+
+**What to reveal, in order of priority:**
+
+1. **Need to know NOW** - Information required for current scene to make sense
+2. **Need to know SOON** - Information required for upcoming plot
+3. **Nice to know** - Enriches understanding, not essential
+4. **Can wonder about** - Intentional mysteries
+5. **Never need to know** - Your notes only
+
+**Rule:** Only reveal from categories 1-2. Sprinkle 3. Preserve 4. Keep 5 hidden.
+
+---
+
+## Revelation Anti-Patterns
+
+### The Info-Dump
+
+**Symptom:** Paragraphs of history/explanation
+**Cure:** Break into small pieces across scenes
+
+**Bad:**
+```
+The War of Shadows was fought 300 years ago between the
+Northern Alliance and the Southern Empire. It lasted
+forty years and killed millions. The Northern Alliance
+won because of their superior magic, which was developed
+by the Archmage Valdris who discovered the principle of
+sympathetic resonance in the crystalline matrices...
+```
+
+**Good:**
+```
+"Nobody crosses the Ashfields."
+"Why?"
+"The war." He spat. "Three centuries dead and the land
+still won't grow. Magic poisoned it."
+"Which war?"
+He looked at her like she'd asked which direction was up.
+"The only one that matters."
+```
+
+### The "As You Know" Dialogue
+
+**Symptom:** Characters explain things they both already know
+**Cure:** Only explain to characters who don't know
+
+**Bad:**
+```
+"As you know, Father, our family has held this castle for
+twelve generations since the founding of the kingdom."
+```
+
+**Good:**
+```
+"Twelve generations," her father said, looking at the walls.
+"And now this."
+She didn't answer. What was there to say?
+```
+
+### The Tour Guide
+
+**Symptom:** Character explains every sight
+**Cure:** Let reader observe without commentary
+
+**Bad:**
+```
+"That's the Temple of the Sun God, built five hundred years
+ago. Over there is the marketplace where merchants from
+across the continent come to trade. And that statue
+commemorates King Aldric the Bold who..."
+```
+
+**Good:**
+```
+The temple dominated the square. Old. Five centuries at least,
+from the architectural style. The market sprawled around it,
+foreign tongues mixing with local shouts. At the center, a
+bronze king watched it all with blind eyes.
+```
+
+### The Convenient Expert
+
+**Symptom:** Perfect source appears exactly when needed
+**Cure:** Establish sources before needed, or work for information
+
+**Bad:**
+```
+"We need to know about ancient dragon magic."
+A man in the corner stood. "I happen to be the world's
+foremost expert on ancient dragon magic."
+```
+
+**Good:**
+```
+"We need to know about ancient dragon magic."
+"There's one person who might know. The hermit in the
+Eastern Waste. She was there when the last dragon died."
+"The Eastern Waste is three weeks of travel."
+"Then we'd better start walking."
+```
+
+---
+
+## Revelation Planning Template
+
+For major world elements, plan revelation:
+
+```
+ELEMENT: [Magic system / Historical event / Cultural fact]
+
+Story need: [Why readers must know this]
+
+REVELATION PLAN:
+- First third: [What hints/fragments]
+- Second third: [What connections/partial reveals]
+- Final third: [What full explanations]
+
+METHOD: [Character discovery / Conflict / Environment / Dialogue / Artifact]
+
+WHAT STAYS HIDDEN: [What readers never fully learn]
+```
+
+---
+
+## Quick Checklist
+
+### Before Writing a Scene
+
+- [ ] What must readers know for this scene to work?
+- [ ] What can readers wonder about after this scene?
+- [ ] Is there any info-dumping to cut?
+- [ ] Does any "as you know" dialogue exist?
+
+### After Drafting
+
+- [ ] Could any exposition be shown instead of told?
+- [ ] Is information revealed at the moment of maximum impact?
+- [ ] Do mysteries created earlier get addressed?
+- [ ] Is the pace of revelation appropriate (not too fast/slow)?
+
+### Per Book
+
+- [ ] Major mysteries established in first third
+- [ ] Connections forming in second third
+- [ ] Satisfying reveals in final third
+- [ ] Some mystery preserved for future
+
+---
+
+## The Ultimate Test
+
+**If readers feel the world is shallow:** You're not implying enough below-surface depth.
+
+**If readers feel confused:** You're not revealing enough surface information.
+
+**If readers feel lectured:** You're revealing too much too directly.
+
+**The sweet spot:** Readers understand enough to follow the story while sensing vastly more beneath.
+
+---
+
+**Related:** See [SKILL.md](./SKILL.md) for the iceberg principle overview.