Skill: Session Orchestration
What This Skill Does
Runs one production session producing investigations for a batch of users. The session agent reads CSVs, selects the correct template per user, spawns one subagent per investigation, validates output, and packages results.
Current Scope
- 29 users × 4 projects = 116 investigations
- 7 viewer templates (blog, magazine, dossier, first-person, comic-text, quantitative, scenario-brief)
- 6 sessions (split by domain cluster for cross-reference coherence)
Session Architecture
| Session | Users | Count | Domain Focus | Templates Used |
|---|
| 1 (TEST) | 01-05 | 20 inv | Middle East Deep Dive: military, conflict, intelligence, diplomacy, oil | dossier (01,03), first-person (02), magazine (04), quantitative (05) |
| 2 | 06-10 | 20 inv | Global Powers: Gulf economics, supply chains, markets, quant, development | magazine (06,10), blog (07), dossier (08), quantitative (09) |
| 3 | 11-15 | 20 inv | Economics & India Markets: inequality, cyber, tech, comparative, Indian sectors | first-person (11), dossier (12), blog (13), magazine (14), quantitative (15) |
| 4 | 16-20 | 20 inv | India & Global Systems: energy policy, trade, South Asia, law, media | magazine (16), first-person (17,20,22), comic-text (18,19) |
| 5 | 21-25 | 20 inv | Society & Future: health, digital rights, nuclear, resources, AI | comic-text (21,24,25), dossier (23), first-person (22) |
| 6 | 26-29 | 16 inv | Additions: Russia/Eurasia, insurance/risk, futures/scenarios, India defense | magazine (26), quantitative (27,29), scenario-brief (28) |
Session 1 runs WITH Ajay (test). Validate quality on 4-5 investigations before running 2-6 autonomously.
Session Agent Workflow
1. Setup
1. Read data/users.csv — filter to this session's users
2. Read data/projects.csv — filter to this session's projects
3. For each user: read their viewer_style → load correct template from templates/
4. Read skills/investigation-autopilot.md
5. Create session output directory: database/session-{N}/
6. Load any completed investigations from prior sessions (for cross-references)
2. For Each User (sequential — one user at a time)
For user in session_users:
template = templates/viewer-{user.viewer_style}.md
For project in user.projects (1-4):
a. Spawn subagent with investigation-autopilot skill
b. Brief subagent with:
- User profile (full row from users.csv)
- Project brief (full row from projects.csv)
- Viewer template (matched to user's viewer_style)
- Cross-reference titles (from already-completed investigations)
- Instruction: "Web search for current March 2026 data on this topic"
c. Receive output: panels.json, knowledge.json, metadata.json
d. Validate output against TEMPLATE-SPECIFIC quality gates
e. If PASS: save to database/{user_id}/{project_number}/
f. If FAIL: log failure, flag for re-run, continue
3. Validation Checklist (per investigation)
Universal checks (all templates):
STRUCTURE:
[ ] panels.json has exactly 25 entries
[ ] Each panel has panel_number, title, content
[ ] Each panel content is 100-300 words (comic-text can be shorter)
[ ] Total word count: 3,500-7,500
KNOWLEDGE:
[ ] knowledge.json has all 8 entity categories
[ ] Total entities >= 100
[ ] Total causal links >= 40
[ ] Causal chains >= 4 (each 4+ steps)
[ ] Themes >= 5
[ ] Cross-references >= 3
[ ] Every entity has a non-empty "role" field
CONTENT:
[ ] No banned phrases (check template's banned list)
[ ] Specific numbers and dates (not vague)
[ ] Web-searched current data present (March 2026)
[ ] Author voice matches user's voice_description
METADATA:
[ ] metadata.json has all required fields
[ ] viewer_style matches user's assignment
[ ] tags array has 8-15 entries
Template-specific checks:
| Template | Additional Checks |
|---|
| blog | Panel 1 is a scene, not a statement. Pull quotes present. |
| magazine | Thesis in first 3 panels. 2+ stat blocks. 2+ pull quotes. Historical context 20+ years. No first person. |
| dossier | Header block in Panel 1. Confidence ratings on claims. 2+ data tables. Risk matrix. Dissenting view. |
| first-person | Panel 1 is sensory scene. 4+ direct quotes. 3+ locations. Opening revisited in close. |
| comic-text | Panel 1 is title card only. 3+ impact-number frames. 2+ character cards. 1+ arrow chain. No paragraph >3 sentences. |
| quantitative | Abstract in Panel 1. Methodology reproducible. 3+ results tables. Robustness checks. Limitations section. |
| scenario-brief | 4+ scenarios + wild card. Probabilities sum ~100%. Comparison table. Indicator dashboard. Robust strategies. |
4. Session Summary
After all investigations in this session:
1. Write database/session-{N}-summary.md:
- Users completed: list with status
- Investigations: X/Y (with failures listed)
- Total entities extracted: sum
- Total causal links: sum
- Cross-references: count (internal to session + to prior sessions)
- Template distribution: how many of each type
- Failures: list with reasons
- Quality notes: borderline passes
2. Create database/session-{N}-crosslinks.json:
- All cross-references from this session
- Entities appearing in 3+ investigations (convergence points)
- Causal chains connecting across investigations
Subagent Briefing Template
When spawning a subagent for one investigation:
TASK: Generate investigation "{project_title}" by {author_name}
USER PROFILE:
- Name: {name}
- Role: {role}
- Location: {location}
- Voice: {voice_description}
- Expertise: {expertise}
- Target audience: {target_audience}
PROJECT BRIEF:
- Title: {title}
- Description: {description}
- Key entities to cover: {key_entities}
- Causal focus: {causal_focus}
- Cross-links to users: {cross_links_to_users}
TEMPLATE: {viewer_style}
Follow the structure from templates/viewer-{viewer_style}.md exactly.
This is a {viewer_style} format investigation — use that template's panel structure,
writing rules, formatting components, and quality gates. Do NOT default to blog format.
WEB SEARCH: Required. Search for current March 2026 data on:
- {key_entities} — current status, recent developments
- Specific numbers: prices, reserves, trade volumes, casualties
- Named institutions and their recent actions/statements
OUTPUT FORMAT:
Return three JSON files:
1. panels.json — array of {panel_number, title, content, word_count}
2. knowledge.json — entities, causal_links, causal_chains, themes, cross_references
3. metadata.json — all fields per spec
QUALITY REQUIREMENTS:
- 100+ entities, 40+ causal links, 4+ chains, 5+ themes
- Every entity has a descriptive role
- Causal verbs: caused, triggered, enabled, funded, weakened, collapsed
- No generic AI phrases
- Specific numbers, dates, named sources from web search
- Author voice distinct and consistent with {voice_description}
- Template-specific quality gates met (see template file)
Cross-Reference Strategy
Investigations reference each other by author name. For this to work:
- Within-session references: The session agent tracks completed investigations and feeds titles to subsequent subagents
- Cross-session references: Load prior session summaries. Reference by author name + title even if not yet written — the content will be consistent because all come from the same projects.csv
- The cross_links_to_users column in projects.csv specifies which users to reference. The subagent should mention those authors by name in at least the final panel.
Context Budget
Each subagent gets:
- User profile (~500 tokens)
- Project brief (~300 tokens)
- Viewer template (~3,000-4,000 tokens depending on template)
- Cross-reference titles (~300 tokens)
- Autopilot skill instructions (~2,500 tokens)
- Total input: ~7,000 tokens
- Output budget: ~15,000 tokens (25 panels × ~200 words × ~1.3 tokens/word + JSON)
Session agent's own context:
- Session management: ~5,000 tokens
- Running tally: grows per investigation (~200 tokens each)
- Must stay under 75% context — hand over if approaching limit
Failure Handling
If a subagent fails:
- Log: which user, which project, what went wrong, which template
- Do NOT retry immediately — continue with next project
- At end of session, re-run failures with adjusted brief
- If still fails: flag for manual review with Ajay
If session agent approaches 75% context:
- Stop after current user completes
- Write handover: users done, remaining, failures, cross-reference state
- Next session agent picks up with full context from handover
Production Order
Session 1 (TEST with Ajay): Users 01-05 → 20 investigations
→ Review quality → Adjust templates/autopilot if needed
→ Ajay approves before continuing
Session 2: Users 06-10 → 20 investigations
Session 3: Users 11-15 → 20 investigations
Session 4: Users 16-20 → 20 investigations
Session 5: Users 21-25 → 20 investigations
Session 6: Users 26-29 → 16 investigations
Total: 116 investigations across 6 sessions