Skip to content

Commit e078728

Browse files
DeveshParagiriDeveshParagiri
committed
style: format files
1 parent f79add7 commit e078728

7 files changed

Lines changed: 242 additions & 11 deletions

File tree

‎.claude/hooks.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"hooks": {
3+
"PostToolUse": [
4+
{
5+
"matcher": "Edit",
6+
"command": "uv run ruff check --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; uv run ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null; true"
7+
},
8+
{
9+
"matcher": "Write",
10+
"command": "[[ \"$CLAUDE_FILE_PATH\" == *.py ]] && { uv run ruff check --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; uv run ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null; } ; true"
11+
}
12+
]
13+
}
14+
}

‎docs/skill-rewrite-plan.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Plan: Rewrite Extropy Skills
2+
3+
## Execution Timing
4+
5+
**WAIT for pending CLI changes before executing this plan.**
6+
7+
Known pending changes:
8+
- `network --generate-config` becoming default behavior
9+
- [Any other CLI changes in progress]
10+
11+
Once CLI is stable, execute this plan against the final CLI state.
12+
13+
---
14+
15+
## Context
16+
17+
The current Extropy skills (6 files, ~1,667 lines) are outdated:
18+
1. **Wrong CLI patterns**: Reference old commands (`extend`, `--study-db` everywhere) that no longer exist
19+
2. **Missing the craft**: Don't teach HOW to write good spec/scenario prompts - just list commands
20+
3. **No real examples**: Generic descriptions instead of concrete, annotated examples
21+
4. **Over-fragmented**: 6 files is too many; user wants 2 focused files
22+
23+
The user provided excellent guidance on what makes good vs bad prompts (see conversation above), plus real examples (ASI announcement, crypto airdrop, inflation shock, Netflix password sharing).
24+
25+
## Goals
26+
27+
1. Teach the **craft** of writing good spec and scenario prompts
28+
2. Use **current CLI** patterns (`spec → scenario → persona → sample → network → simulate`)
29+
3. Include **annotated real examples** showing why they work
30+
4. Consolidate to **2 files**: SKILL.md (the craft) + REFERENCE.md (commands/troubleshooting)
31+
32+
---
33+
34+
## File Structure
35+
36+
### SKILL.md (~500 lines)
37+
The main skill entry point. Focuses on **understanding Extropy** and **writing effective prompts**.
38+
39+
**Sections:**
40+
1. **What Extropy Is** (~50 lines)
41+
- The pitch: **Predictive intelligence through population simulation** (not surveys, not polls)
42+
- Synthetic agents grounded in real-world distributions, connected in social networks, each reasoning individually via LLM
43+
- What you get back:
44+
- Distributional predictions by segment
45+
- **Open-ended responses** when you don't know the outcome space (let agents tell you what they'd do, discover categories post-hoc)
46+
- Reasoning traces explaining *why*
47+
- Opinion dynamics over time
48+
- Network effects and conversation transcripts
49+
50+
2. **What It Can and Can't Do** (~30 lines)
51+
- Works well: policy, pricing, product, crisis, messaging, community
52+
- Limitations: no org charts, no real-time, no individual prediction
53+
54+
3. **The Craft of Spec Prompts** (~100 lines)
55+
- Mental model: "Constrain WHO, let LLM discover WHAT"
56+
- Spec creates reusable base population; scenario extends it
57+
- **Bad patterns** with examples:
58+
- Too vague: "Americans"
59+
- Too prescriptive: dictating exact brackets
60+
- Too narrow: over-specialized for one scenario
61+
- **Good patterns** with examples:
62+
- Clear population boundary
63+
- General attitudinal/psychological dimensions (trust, risk, tech adoption)
64+
- Reusable across scenarios
65+
- **Annotated example**: The US adults spec from user's chat
66+
67+
4. **The Craft of Scenario Prompts** (~150 lines)
68+
- Mental model: Scenario extends base with event-specific attributes
69+
- **The evolving test**: "Does the network change the outcome?"
70+
- Non-evolving: concrete personal decisions, population heterogeneity is the story (Netflix)
71+
- Evolving: information/credibility dynamics, social influence matters (ASI)
72+
- **Bad patterns**:
73+
- Too abstract: no concrete details
74+
- Predetermined framing: telling agents how to feel
75+
- Wrong timeline choice: evolving when should be static, or vice versa
76+
- Too many timeline events: drowns out network propagation
77+
- Wrong timestep granularity
78+
- **Good patterns**:
79+
- Concrete and specific: named entities, exact numbers
80+
- Neutral framing: present facts, let agents disagree
81+
- Strategic timeline events: 2-4 max, spaced for propagation
82+
- **Timestep table**: hours/days/weeks/months with use cases
83+
- **Annotated examples**:
84+
- Non-evolving: Netflix password sharing (from extropy.run)
85+
- Evolving: ASI announcement (from user's chat)
86+
- Edge case: Inflation shock (hybrid dynamics)
87+
88+
5. **Quick Pipeline** (~50 lines)
89+
- Current CLI flow with correct commands
90+
- Study folder structure
91+
- Common flags
92+
93+
6. **Fidelity and Cost** (~30 lines)
94+
- Low/medium/high tiers
95+
- When to use each
96+
- Cost estimates
97+
98+
7. **Operating Mode** (~40 lines)
99+
- **Always set `cli.mode agent`** at start of session for JSON output
100+
- Model configuration: `extropy config set simulation.strong`, etc.
101+
- **Escalation policy**: When to stop and ask user vs proceed autonomously
102+
- Escalate: same error twice, core assumptions change, cost vs accuracy tradeoff, sensitive content
103+
- Don't escalate: normal pipeline execution, validation passes, expected behavior
104+
- **Non-interactive flags**: `-y` to skip confirmations, `--use-defaults` for spec
105+
106+
8. **Module Reference** (~20 lines)
107+
- Points to REFERENCE.md for commands, troubleshooting, analysis
108+
109+
### REFERENCE.md (~400 lines)
110+
Condensed operational reference. Everything you need to run simulations.
111+
112+
**Sections:**
113+
1. **Command Reference** (~150 lines)
114+
- Condensed from docs/commands.md
115+
- Each command: purpose, key flags, example
116+
- Focus on most-used options, not exhaustive
117+
118+
2. **Study Folder Structure** (~30 lines)
119+
- Directory layout
120+
- File naming conventions (v1, v2, etc.)
121+
122+
3. **Results & Analysis** (~80 lines)
123+
- Condensed from ANALYSIS.md
124+
- How to read results
125+
- Segment analysis
126+
- Agent deep dives
127+
- Export commands
128+
129+
4. **Troubleshooting** (~100 lines)
130+
- Condensed from TROUBLESHOOTING.md
131+
- Common failure patterns
132+
- Quality gates (quick checklist)
133+
- When to escalate
134+
135+
5. **Configuration** (~60 lines)
136+
- **Agent mode setup**: `extropy config set cli.mode agent`
137+
- Model configuration:
138+
- `models.strong` / `models.fast` for pipeline (spec, scenario, persona)
139+
- `simulation.strong` / `simulation.fast` for simulation passes
140+
- API keys (env vars): OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, AZURE_API_KEY
141+
- Rate limiting: `simulation.rate_tier`, RPM/TPM overrides
142+
- Typical config for agent use:
143+
```bash
144+
extropy config set cli.mode agent
145+
extropy config set models.strong openai/gpt-4o
146+
extropy config set simulation.strong anthropic/claude-sonnet-4.5
147+
```
148+
149+
---
150+
151+
## Files to Delete
152+
153+
After creating new SKILL.md and REFERENCE.md, delete:
154+
- `skills/extropy/OPERATIONS.md` (absorbed into REFERENCE.md)
155+
- `skills/extropy/SCENARIOS.md` (absorbed into SKILL.md)
156+
- `skills/extropy/ANALYSIS.md` (absorbed into REFERENCE.md)
157+
- `skills/extropy/TROUBLESHOOTING.md` (absorbed into REFERENCE.md)
158+
- `skills/extropy/REPORT_TEMPLATE.md` (delete - too rigid, Claude can generate reports on demand)
159+
160+
---
161+
162+
## Key Content to Include
163+
164+
### Spec Example (Good)
165+
```bash
166+
extropy spec "Nationally representative US adult population (18-80). Must capture the demographic, economic, and attitudinal fault lines that drive divergent responses to major national events — especially technology disruption, economic shocks, and cultural controversies. Beyond standard demographics, prioritize attributes that determine HOW people process and react to news: technology adoption posture, media ecosystem and information sources, institutional trust level, financial margin and economic anxiety, consumer identity and brand relationship patterns, social media behavior and influence. Geographic distribution should span urban/suburban/rural across all major US regions." -o population.v1.yaml -y
167+
```
168+
169+
**Why it works**: Defines boundary (US adults 18-80), hints at behavioral dimensions without dictating exact categories, includes attitudinal layer (trust, tech adoption, media habits), reusable across many scenarios.
170+
171+
### Scenario Example - Non-Evolving (Netflix)
172+
```bash
173+
extropy scenario "Netflix announces enforcement of password sharing policy. Subscribers who share their password with people outside their household must either: pay $8/month for an extra member slot, remove shared users, or accept that shared users will be blocked. The policy takes effect in 30 days. Coverage is widespread across tech news, social media, and mainstream outlets." -o netflix-password -y
174+
```
175+
176+
**Why non-evolving**: The decision is concrete and personal. Population heterogeneity (income, household composition, alternatives awareness) drives the interesting splits. My neighbor's opinion doesn't change whether I can afford $8/month.
177+
178+
### Scenario Example - Evolving (ASI)
179+
```bash
180+
extropy scenario "OpenAI holds a press conference announcing they have achieved artificial superintelligence — a system that demonstrably exceeds human cognitive ability across every domain. Sam Altman presents benchmark results showing the system outperforms top experts in science, law, medicine, strategy, and creative reasoning. The announcement is covered live on all major networks. Timeline events: Day 1 - OpenAI's announcement and initial reactions. Day 3 - Anthropic and Google DeepMind release statements confirming they have independently reached similar capabilities. Day 5 - xAI and Meta confirm the same; Congress announces emergency hearings. Day 7 - Deloitte announces it will replace 30% of its workforce with AI systems within 12 months." -o asi-announcement --timeline evolving -y
181+
```
182+
183+
**Why evolving**: Information/credibility dynamics matter. Day 1 people can dismiss as hype. By Day 5 when every lab confirms, denial breaks. Day 7 makes it personal. Network propagation happens in the gaps between events.
184+
185+
### The Evolving Test
186+
> "Does the network change the outcome? If agents talking to each other would meaningfully shift results compared to running independent LLM calls, use evolving. If not, non-evolving is cleaner and more honest."
187+
188+
### Timestep Table
189+
| Unit | Use When |
190+
|------|----------|
191+
| Hours | Active crisis, market crash, disaster response |
192+
| Days | Viral news, product launches, policy announcements |
193+
| Weeks | Adoption curves, behavior change, campaign effects |
194+
| Months | Cultural shifts, market trends, policy adaptation |
195+
196+
---
197+
198+
## Verification
199+
200+
After implementation:
201+
1. Run `extropy --help` and verify all referenced commands exist
202+
2. Run through quick pipeline example to ensure commands work
203+
3. Check that SKILL.md frontmatter is valid YAML
204+
4. Verify cross-references between SKILL.md and REFERENCE.md are correct
205+
5. Test that skill loads in Claude Code: `/extropy`
206+

‎extropy/cli/commands/network.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -758,8 +758,6 @@ def _resolve_scenario(
758758
return name, version
759759

760760

761-
762-
763761
def _save_network(
764762
study_db: Path,
765763
scenario_name: str,

‎extropy/cli/commands/sample.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -334,8 +334,6 @@ def _resolve_scenario(
334334
return name, version
335335

336336

337-
338-
339337
def _save_to_db(
340338
db_path: Path,
341339
scenario_name: str,

‎extropy/cli/commands/spec.py‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -277,9 +277,7 @@ def spec_command(
277277
focus_str = f", focus: {agent_focus}" if agent_focus else ""
278278

279279
if not agent_mode:
280-
console.print(
281-
f"[green]✓[/green] Context sufficient{geo_str}{focus_str}"
282-
)
280+
console.print(f"[green]✓[/green] Context sufficient{geo_str}{focus_str}")
283281

284282
# Step 1: Attribute Selection
285283
console.print()

‎extropy/scenario/timeline.py‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,12 @@
9696
),
9797
},
9898
},
99-
"required": ["scenario_type", "timestep_unit", "max_timesteps", "background_context"],
99+
"required": [
100+
"scenario_type",
101+
"timestep_unit",
102+
"max_timesteps",
103+
"background_context",
104+
],
100105
}
101106

102107

@@ -236,7 +241,11 @@ def generate_timeline(
236241
llm_unit = response.get("timestep_unit")
237242
llm_max = response.get("max_timesteps")
238243
if llm_unit:
239-
unit_map = {"minute": TimestepUnit.MINUTE, "hour": TimestepUnit.HOUR, "day": TimestepUnit.DAY}
244+
unit_map = {
245+
"minute": TimestepUnit.MINUTE,
246+
"hour": TimestepUnit.HOUR,
247+
"day": TimestepUnit.DAY,
248+
}
240249
resolved_unit = unit_map.get(llm_unit, simulation_config.timestep_unit)
241250
simulation_config = SimulationConfig(
242251
max_timesteps=llm_max if llm_max else simulation_config.max_timesteps,

‎tests/test_compiler.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,11 @@ def test_creates_valid_scenario(
175175
],
176176
)
177177

178-
mock_timeline.return_value = ([], None, _determine_simulation_config()) # No timeline events, no background
178+
mock_timeline.return_value = (
179+
[],
180+
None,
181+
_determine_simulation_config(),
182+
) # No timeline events, no background
179183

180184
spec, validation_result = create_scenario(
181185
description="Test product launch scenario",
@@ -257,7 +261,11 @@ def test_progress_callback_called(
257261
],
258262
)
259263

260-
mock_timeline.return_value = ([], None, _determine_simulation_config()) # No timeline events, no background
264+
mock_timeline.return_value = (
265+
[],
266+
None,
267+
_determine_simulation_config(),
268+
) # No timeline events, no background
261269

262270
progress_calls = []
263271

0 commit comments

Comments
 (0)