architect

## Runtime Configuration (Step 0 — before any processing) Read these files to configure domain-specific behavior: 1. **`ops/derivation-manifest.md`** — vocabulary mapping, platform hints - Use `vocabulary.notes` for the notes folder name - Use `vocabulary.note` / `vocabulary.note_plural` for note type references - Use `vocabulary.topic_map` / `vocabulary.topic_map_plural` for MOC references - Use `vocabulary.inbox` for the inbox folder name - Use `vocabulary.cmd_reflect` for connection-finding command name - Use `vocabulary.cmd_reweave` for backward-pass command name - Use `vocabulary.cmd_verify` for verification command name - Use `vocabulary.architect` for the command name in output 2. **`ops/config.yaml`** — processing depth, pipeline chaining, automation settings 3. **`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:** 1. Locate system files and detect platform 2. Read derivation record for design intent 3. Analyze health data (recent report or live check) 4. Scan for friction patterns across operational surfaces 5. Consult research to ground evidence in specific claims 6. Generate 3-5 ranked recommendations with full evidence chains 7. 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/`: ```bash # 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:** ```bash # 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\]\]" {vocabulary.notes}/ 2>/dev/null | wc -l | tr -d ' ') [[ "$LINKS" -eq 0 ]] && echo "ORPHAN: $NAME" done # Find dangling links grep -ohP '\[\[([^\]]+)\]\]' {vocabulary.notes}/*.md | sort -u | while read -r link; do NAME=$(echo "$link" | sed 's/\[\[//;s/\]\]//') [[ ! -f "{vocabulary.notes}/$NAME.md" ]] && echo "DANGLING: $NAME" done # Count inbox items INBOX_COUNT=$(ls -1 {vocabulary.inbox}/ 2>/dev/null | wc -l | tr -d ' ') # MOC sizes grep -rl '^type: moc' {vocabulary.notes}/*.md 2>/dev/null | while read -r moc; do COUNT=$(grep -c '^\- \[\[' "$moc" 2>/dev/null) echo "MOC: $(basename "$moc" .md) = $COUNT notes" done # Missing descriptions grep -rL '^description:' {vocabulary.notes}/*.md 2>/dev/null ``` Record all findings as evidence for Phase 6. Every finding must include the specific notes, links, or fields affected — not just counts. --- ## PHASE 4: Read Friction Scan for friction patterns across multiple operational surfaces. Friction is the gap between how the system should work and how it actually works. ### 4a. Observation Notes ```bash # Find all pending observations grep -rl '^status: pending' ops/observations/ 2>/dev/null ``` Read each pending observation. Categorize by type: | Category | Signal | Evidence Value | |----------|--------|---------------| | Friction | "this was harder than it should be" | High — points to workflow mismatch | | Process Gap | "there is no way to do X" | High — missing capability | | Surprise | "I did not expect this behavior" | Medium — misaligned expectations | | Methodology | "I learned that X works better" | Medium — operational insight | | Quality | "the output was not good enough" | High — quality gate failure | Count occurrences per category. 3+ items in the same category = a friction pattern worth investigating. ### 4b. Methodology Notes ```bash # Read all methodology notes ls ops/methodology/*.md 2>/dev/null ``` Read each methodology note. Look for: - Recurring themes across multiple notes - Tensions between stated methodology and actual practice - Behavioral corrections that suggest the original design was wrong - Methodology notes with multiple evidence entries (strong signal) ### 4c. Session Logs ```bash # Read recent session logs (last 5-10 sessions) ls -t ops/sessions/*.md 2>/dev/null | head -10 ``` Scan session logs for: - Repeated complaints or workarounds - Steps that get skipped consistently - Patterns in what the agent does vs what the system recommends - Error patterns or tool failures ### 4d. Self Space If self/ exists, read: - `self/methodology.md` — how the agent describes its own process - `self/goals.md` — whether current priorities align with system capabilities - `self/memory/` — any notes about workflow frustrations ### 4e. Build Friction Inventory Compile all friction evidence into a structured inventory: ``` Friction Inventory: 1. [category]: [description] Frequency: [N observations across M sessions] Sources: [filenames] Impact: [what breaks or degrades] System area: [which dimension/skill/workflow affected] 2. [category]: [description] ... ``` Rank by frequency * impact. The most frequent, highest-impact friction patterns get priority in Phase 6. --- ## PHASE 5: Consult Research Ground the evidence in research. This is what separates /architect from ad-hoc troubleshooting — every recommendation connects to specific research claims, not general intuition. Read the reference files: | Reference | What It Contains | When To Use | |-----------|-----------------|-------------| | `${CLAUDE_PLUGIN_ROOT}/reference/dimension-claim-map.md` | Which research claims inform which dimensions | Mapping friction to dimension adjustments | | `${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md` | How dimension choices create pressure on others | Cascade analysis for proposed changes | | `${CLAUDE_PLUGIN_ROOT}/reference/methodology.md` | Universal principles and processing pipeline | Grounding recommendations in first principles | | `${CLAUDE_PLUGIN_ROOT}/reference/failure-modes.md` | 10 failure modes with domain vulnerability matrix | Connecting friction to known failure patterns | | `${CLAUDE_PLUGIN_ROOT}/reference/tradition-presets.md` | Named points in configuration space | Alternative configurations to consider | | `${CLAUDE_PLUGIN_ROOT}/reference/vocabulary-transforms.md` | Universal-to-domain term mapping | Ensuring output uses domain vocabulary | | `${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md` | Self/notes/ops architecture and boundary rules | Three-space boundary analysis | | `${CLAUDE_PLUGIN_ROOT}/reference/derivation-validation.md` | Validation tests for derived systems | Post-change validation criteria | | `${CLAUDE_PLUGIN_ROOT}/reference/evolution-lifecycle.md` | Seed-evolve-reseed patterns, friction-driven adoption | When to evolve vs when to reseed | | `${CLAUDE_PLUGIN_ROOT}/reference/self-space.md` | Agent identity generation and self/ architecture | Self-space related recommendations | ### Research Matching Process For each friction pattern or health issue identified in Phases 3-4: **Step 1: Check dimension-claim-map.md** - Which research claims relate to this issue? - What dimension positions do those claims support? - Does the current configuration conflict with what research recommends? **Step 2: Check interaction-constraints.md** - Is this friction a CASCADE effect from a dimension mismatch? - Would changing one dimension to fix this create pressure on another? - Are there compensating mechanisms documented? **Step 3: Check failure-modes.md** - Does this match a known failure mode pattern? - Was this failure mode flagged as HIGH risk during derivation? - What does the failure mode document say about mitigation? **Step 4: Search the knowledge graph** - Use `mcp__qmd__deep_search` to find claims that address the specific friction - Fall back to `mcp__qmd__vector_search` if hybrid search is unavailable - If MCP is unavailable, fall back to qmd CLI (`qmd query` then `qmd vsearch`) - Fall back to reading bundled reference files directly only if both MCP and qmd CLI are unavailable - Search for the friction pattern described in natural language - Search for the system area affected - Search for proposed solution concepts ``` mcp__qmd__deep_search query="[friction description in natural language]" limit=10 ``` Read the top results. For each relevant claim: - Note the claim title (for citation in recommendations) - Note what the claim argues - Note how it applies to the current friction **The goal is to connect EVERY recommendation to specific research, not general intuition.** --- ## PHASE 6: Generate Recommendations Synthesize evidence from Phases 2-5 into 3-5 concrete recommendations, ranked by impact-to-effort ratio. ### Ranking Criteria | Criterion | Scale | What It Measures | |-----------|-------|-----------------| | Impact | high / medium / low | How much does this improve the system? | | Effort | minutes / hours / days | How much work to implement? |