apex-evolve

name	apex-evolve
description	Build and maintain apex articles—human-readable synthesis pieces.

Apex Evolve

Build and maintain apex articles through creation, evolution, and length management.

When to Use

• Creating a new apex article from the approved list
• Evolving an existing apex article when source content has changed
• Checking which apex articles need attention

Invocation

/apex-evolve create "Article Title"
/apex-evolve evolve [article-slug]
/apex-evolve check

Modes

Mode 1: create

Generate a new apex article from scratch.

Input: Article title from the approved list in obsidian/apex/apex-articles.md

Process:

1. Look up the article in the master list to get source articles and thesis
2. Read all source articles to understand the material
3. Read obsidian/project/writing-style.md for apex article guidelines
4. Synthesize into a narrative that weaves sources together
5. Target length: 2500-4000 words
6. Create with required frontmatter (see below)

Output: New apex article at obsidian/apex/[slug].md

Mode 2: evolve

Update an existing apex article when sources have changed.

Input: Specific article slug, or omit to auto-select stalest

Process: See 10-step evolution process below

Output: Improved article + review archive

Mode 3: check

Report which apex articles need evolution.

Process:

1. Read all apex articles and their apex_sources frontmatter
2. For each source, check its modified date against the apex article's apex_last_synthesis
3. Report articles with stale sources, ordered by priority

Output: List of articles needing attention with staleness scores

---

Frontmatter Schema

Apex articles use standard frontmatter plus apex-specific fields:

---
title: "Article Title"
created: 2026-01-24
modified: 2026-01-24
human_modified: null
ai_modified: 2026-01-24T00:00:00+00:00
draft: false
topics: []
concepts: []
related_articles: []

ai_contribution: 100
author: null
ai_system: claude-opus-4-5-20251101
ai_generated_date: 2026-01-24
last_curated: null

# Apex-specific fields
apex_sources:
  - topics/free-will
  - topics/agent-causation
  - concepts/mental-causation
apex_last_synthesis: 2026-01-24T00:00:00+00:00
apex_thesis: "One-sentence thesis statement"
---

---

Evolution Process (10 Steps)

Step 1: Select Article

If article specified, use it. Otherwise, auto-select:

1. Read all apex articles in obsidian/apex/
2. For each, calculate staleness score:
   • Count sources modified after apex_last_synthesis
   • Score = days_stale × changed_source_count
3. Select highest-scoring article

Step 2: Identify Changed Sources

Compare each source's modified date to apex_last_synthesis. List all changed sources.

Step 3: Read Changed Sources

Read the full content of each changed source to understand new material.

Step 4: Pessimistic Review

Apply three critical personas:

Clarity Critic: Where is the prose unclear, jargon-heavy, or hard to follow? Where does the narrative lose the reader?

Redundancy Hunter: What passages repeat information? Where does the article say the same thing twice? What can be cut without losing meaning?

Narrative Flow Analyst: Where does the argument structure break down? Are transitions smooth? Does the piece build to its conclusion?

Step 5: Optimistic Review

Apply three supportive personas:

Connection Finder: What new connections from changed sources should be woven in? What synthesis opportunities exist?

Synthesis Strengthener: Where can the article better show how pieces fit together? Where is the "so what" unclear?

Human Reader Advocate: What would make this more engaging to read? Where does it feel like a reference rather than a narrative?

Step 6: Length Assessment

1. Count current word length
2. Compare to target range: 2500-4000 words
3. Note whether condensation or expansion is needed

Step 7: Apply Improvements

Always do:

• Fix issues identified by pessimistic review
• Integrate insights from changed sources
• Strengthen synthesis per optimistic review

If over 4000 words (condensation required):

• Remove redundant passages identified by Redundancy Hunter
• Tighten prose: eliminate filler words, combine sentences
• Move detailed explanations to source articles; replace with links
• Remove sections that duplicate what sources already cover well
• Preserve the narrative arc while reducing word count

If under 2500 words (expansion needed):

• Expand synthesis sections showing connections between sources
• Add transitions that guide the reader through the argument
• Deepen the narrative arc with richer examples

Step 8: Update Frontmatter

ai_modified: [current UTC timestamp]
apex_last_synthesis: [current UTC timestamp]

Adjust ai_contribution if human edits were preserved.

Step 9: Create Review Archive

Create obsidian/reviews/apex-evolve-[date]-[slug].md containing:

• Article reviewed
• Changed sources identified
• Pessimistic review findings (3 personas)
• Optimistic review findings (3 personas)
• Length assessment (before/after word counts)
• Summary of changes made

Step 10: Log and Commit

1. Log to obsidian/workflow/changelog.md:

   ## [timestamp] apex-evolve
   - **Status**: Complete
   - **Article**: [title]
   - **Changed sources**: [count]
   - **Word count**: [before] → [after]
   - **Review**: reviews/apex-evolve-[date]-[slug].md
   

2. Create git commit:

   feat(apex): Evolve [article-title]
   
   - Integrated changes from [N] updated sources
   - [Brief summary of improvements]
   

---

Article Structure

Apex articles follow this structure:

# [Title]

[Opening paragraph stating the integrated thesis - what this synthesis argues]

## [Narrative Section 1]

[Build the argument, drawing from multiple sources]
[Link to sources: "As explored in [[source-article]]..."]

## [Narrative Section 2]

[Continue building, showing connections between ideas]

## [Additional sections as needed]

## Synthesis

[Show how the pieces fit together in a way individual articles don't]
[This is the unique value of the apex article]

## Relation to Site Perspective

[Connect to tenets - required for all articles]

## Source Articles

This apex article synthesizes:
- [[source-1|Source 1 Title]]
- [[source-2|Source 2 Title]]
- ...

---

Length Management Guidelines

Target: 2500-4000 words

Why this range:

• Under 2500: Not enough synthesis to justify an apex article
• Over 4000: Becomes unwieldy for human readers; defeats the purpose

Condensation techniques:

• "As [[source-article]] explores in detail..." (link instead of repeat)
• Combine related paragraphs
• Remove hedging language that adds words without adding meaning
• Cut examples that illustrate the same point

Expansion techniques:

• "This connects to [[other-source]] because..." (show synthesis)
• Add transitional paragraphs between major sections
• Deepen the "why this matters" throughout

---

Cross-Review Integration

When other skills create or modify content that's an apex source:

1. After /expand-topic or /research-topic completes
2. Check if the new/modified article is in any apex article's apex_sources
3. If yes, add to obsidian/workflow/todo.md:

   - [ ] P2 apex-evolve: [apex-article-slug] — source [modified-article] updated
   

This ensures apex articles stay current without manual tracking.

---

Important

• Approved subjects only: Only create apex articles from the master list in obsidian/apex/apex-articles.md
• Human-first: Unlike topics/concepts, apex articles prioritize narrative flow over LLM-atomic structure
• Media-neutral language: Never use the phrase "apex article" in the article content itself. Content may be reproduced in contexts where our internal terminology is unknown. Write as standalone prose.
• Condense actively: Evolution must maintain length discipline; don't let articles grow unbounded
• Link extensively: Apex articles are synthesis—they should link heavily to source articles
• Preserve thesis: Each apex article has a thesis; edits should strengthen it, not dilute it