Runtime Configuration (Step 0 — before any processing)
Read these files to configure domain-specific behavior:
-
ops/derivation-manifest.md— vocabulary mapping, platform hints- Use
vocabulary.notesfor the notes folder name - Use
vocabulary.note/vocabulary.note_pluralfor note type references - Use
vocabulary.topic_map/vocabulary.topic_map_pluralfor MOC references - Use
vocabulary.inboxfor the inbox folder name - Use
vocabulary.cmd_reflectfor connection-finding command name - Use
vocabulary.cmd_reweavefor backward-pass command name - Use
vocabulary.cmd_verifyfor verification command name - Use
vocabulary.architectfor the command name in output
- Use
-
ops/config.yaml— processing depth, pipeline chaining, automation settings -
ops/derivation.md— original derivation record (the design intent baseline)
If these files don't exist, use universal defaults and warn the user.
EXECUTE NOW
Target: $ARGUMENTS
Parse immediately:
- If target names a specific area (e.g., "schema", "processing", "MOC structure"): focus analysis on that area
- If target is empty: run full-system analysis across all dimensions
- If target is
--dry-run: run analysis but do not offer implementation
Execute these phases sequentially:
- Locate system files and detect platform
- Read derivation record for design intent
- Analyze health data (recent report or live check)
- Scan for friction patterns across operational surfaces
- Consult research to ground evidence in specific claims
- Generate 3-5 ranked recommendations with full evidence chains
- Present to user and implement on approval
START NOW. Reference below defines the seven-phase workflow.
Philosophy
Evidence beats intuition. Research beats habit.
Every rule in the context file was a hypothesis. Every skill workflow was a design choice. Hypotheses need testing against operational reality. This skill connects three evidence streams — health data, friction patterns, and research claims — to produce specific, actionable recommendations.
You are not guessing what might help. You are diagnosing what IS happening (health + friction) and prescribing what research says SHOULD happen. Every recommendation traces to specific evidence. "I think this would be better" is not a recommendation. "Health shows 12 orphans, friction log shows repeated orphan complaints, research claim [[orphan notes decay faster than connected ones]] supports adding a condition-triggered reweave pass" — THAT is a recommendation.
The 25% meta-work budget: In a 60-minute session, at most 15 minutes should be spent on system evolution. If a recommendation estimates >15 minutes to implement, the recommendation should be "defer to next session." The system serves the work, not the other way around.
INVARIANT: Architect NEVER auto-implements. Every recommendation requires explicit user approval before any files are modified. This prevents the cognitive outsourcing failure mode — the human must remain in the judgment loop for system evolution.
PHASE 1: Locate
Automated. No user interaction needed.
Detect the platform and find the system's key files:
Check filesystem:
.claude/ directory exists -> platform = "claude-code"
Neither -> platform = "minimal"
Locate these files (paths vary by domain vocabulary):
| File Type | What To Find | Typical Locations |
|---|---|---|
| Context file | System methodology and rules | CLAUDE.md, README.md |
| Self space | Agent identity and memory | self/identity.md, self/methodology.md, self/goals.md |
| Ops directory | Operational infrastructure | ops/derivation.md, ops/config.yaml, ops/sessions/, ops/observations/, ops/health/ |
| Notes directory | Primary knowledge directory | {vocabulary.notes}/ (may be domain-named: reflections/, concepts/, etc.) |
| Queue system | Pipeline state | ops/queue/queue.yaml or ops/queue/queue.json |
| Templates | Note schemas | ops/templates/ or templates/ |
| Methodology | Learned patterns | ops/methodology/ |
If ops/derivation.md does not exist: Warn the user: "No derivation record found. Recommendations will be based on current state analysis only, without historical context of design decisions."
If ops/config.yaml does not exist: Warn: "No config file found. Using observed behavior to infer current configuration."
Record all file locations for use in subsequent phases.
PHASE 2: Read Derivation
Read ops/derivation.md to understand the system's original design intent. This is the baseline against which drift is measured.
Extract from derivation:
| Element | What To Look For | Why It Matters |
|---|---|---|
| Dimension positions | The 8 configuration dimensions and their derived values | Baseline for drift detection |
| Conversation signals | What the user said that drove each choice | Understanding original intent |
| Personality | Warmth, formality, opinionatedness, emotional awareness | Voice consistency check |
| Vocabulary mapping | Universal-to-domain term translations | Output must use domain language |
| Coherence validation | What constraints were active at derivation time | Know which constraints to re-check |
| Failure mode risks | Which failure modes were flagged as HIGH risk | Prioritize monitoring these |
Also read ops/config.yaml — this is the live operational config that may have drifted from derivation. Compare dimension positions between derivation and config:
For each of the 8 dimensions:
derivation_value = [from ops/derivation.md]
config_value = [from ops/config.yaml]
drifted = derivation_value != config_value
Record any drift for Phase 6. Drift is not inherently bad — it may represent healthy evolution. But UNRECOGNIZED drift creates incoherence.
If a specific focus area was requested ($ARGUMENTS), note which dimensions and failure modes are most relevant to that area and prioritize them in subsequent phases.
PHASE 3: Health Analysis
Check for a recent health report in ops/health/:
# Find health reports from the last 7 days
find ops/health/ -name "*.md" -mtime -7 2>/dev/null | sort -r | head -1
If a recent report exists: Read it fully. Extract every FAIL and WARN item as structured evidence:
For each FAIL/WARN:
category: [schema | orphan | link | description | stale | moc | boundary | throughput]
severity: [FAIL | WARN]
detail: [specific finding — which notes, which fields, which links]
count: [how many instances]
If no recent report exists: Run a live health assessment. Check each category:
| Category | How to Check | FAIL Threshold | WARN Threshold |
|---|---|---|---|
| Schema compliance | grep -rL '^description:' {vocabulary.notes}/*.md | N/A | Any note missing required fields |
| Orphan detection | Notes with zero incoming wiki-links (scan for [[filename]] across all notes) | N/A | Any orphan |
| Link health | Wiki-links pointing to non-existent files | Any dangling link | N/A |
| Three-space boundaries | Content in wrong space (notes in ops/, operational files in notes/) | N/A | Any violation |
| Processing throughput | Count inbox items vs notes count | >3:1 ratio | >2:1 ratio |
| Stale notes | Notes with <2 incoming links AND not modified in last 30 days | N/A | >15% of notes |
| MOC coherence | Note count per MOC | N/A | >40 notes (split candidate) or <5 (merge candidate) |
| Description quality | Descriptions that restate the title without adding information | N/A | Any restatement |
Live check implementation:
# Count total notes
NOTE_COUNT=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')
# Find orphans (notes with no incoming links)
for f in {vocabulary.notes}/*.md; do
NAME=$(basename "$f" .md)
LINKS=$(grep -rl "\[\[$NAME\]\]" {v