arscontexta 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (418) hide show
  1. package/.claude-plugin/marketplace.json +11 -0
  2. package/.claude-plugin/plugin.json +22 -0
  3. package/README.md +683 -0
  4. package/agents/knowledge-guide.md +49 -0
  5. package/bin/cli.mjs +66 -0
  6. package/generators/agents-md.md +240 -0
  7. package/generators/claude-md.md +379 -0
  8. package/generators/features/atomic-notes.md +124 -0
  9. package/generators/features/ethical-guardrails.md +58 -0
  10. package/generators/features/graph-analysis.md +188 -0
  11. package/generators/features/helper-functions.md +92 -0
  12. package/generators/features/maintenance.md +164 -0
  13. package/generators/features/methodology-knowledge.md +70 -0
  14. package/generators/features/mocs.md +144 -0
  15. package/generators/features/multi-domain.md +61 -0
  16. package/generators/features/personality.md +71 -0
  17. package/generators/features/processing-pipeline.md +428 -0
  18. package/generators/features/schema.md +149 -0
  19. package/generators/features/self-evolution.md +229 -0
  20. package/generators/features/self-space.md +78 -0
  21. package/generators/features/semantic-search.md +99 -0
  22. package/generators/features/session-rhythm.md +85 -0
  23. package/generators/features/templates.md +85 -0
  24. package/generators/features/wiki-links.md +88 -0
  25. package/generators/soul-md.md +121 -0
  26. package/hooks/hooks.json +45 -0
  27. package/hooks/scripts/auto-commit.sh +44 -0
  28. package/hooks/scripts/session-capture.sh +35 -0
  29. package/hooks/scripts/session-orient.sh +86 -0
  30. package/hooks/scripts/write-validate.sh +42 -0
  31. package/methodology/AI shifts knowledge systems from externalizing memory to externalizing attention.md +59 -0
  32. package/methodology/BM25 retrieval fails on full-length descriptions because query term dilution reduces match scores.md +39 -0
  33. package/methodology/IBIS framework maps claim-based architecture to structured argumentation.md +58 -0
  34. package/methodology/LLM attention degrades as context fills.md +49 -0
  35. package/methodology/MOC construction forces synthesis that automated generation from metadata cannot replicate.md +49 -0
  36. package/methodology/MOC maintenance investment compounds because orientation savings multiply across every future session.md +41 -0
  37. package/methodology/MOCs are attention management devices not just organizational tools.md +51 -0
  38. package/methodology/PKM failure follows a predictable cycle.md +50 -0
  39. package/methodology/ThreadMode to DocumentMode transformation is the core value creation step.md +52 -0
  40. package/methodology/WIP limits force processing over accumulation.md +53 -0
  41. package/methodology/Zeigarnik effect validates capture-first philosophy because open loops drain attention.md +42 -0
  42. package/methodology/academic research uses structured extraction with cross-source synthesis.md +566 -0
  43. package/methodology/adapt the four-phase processing pipeline to domain-specific throughput needs.md +197 -0
  44. package/methodology/agent notes externalize navigation intuition that search cannot discover and traversal cannot reconstruct.md +48 -0
  45. package/methodology/agent self-memory should be architecturally separate from user knowledge systems.md +48 -0
  46. package/methodology/agent session boundaries create natural automation checkpoints that human-operated systems lack.md +56 -0
  47. package/methodology/agent-cognition.md +107 -0
  48. package/methodology/agents are simultaneously methodology executors and subjects creating a unique trust asymmetry.md +66 -0
  49. package/methodology/aspect-oriented programming solved the same cross-cutting concern problem that hooks solve.md +39 -0
  50. package/methodology/associative ontologies beat hierarchical taxonomies because heterarchy adapts while hierarchy brittles.md +53 -0
  51. package/methodology/attention residue may have a minimum granularity that cannot be subdivided.md +46 -0
  52. package/methodology/auto-commit hooks eliminate prospective memory failures by converting remember-to-act into guaranteed execution.md +47 -0
  53. package/methodology/automated detection is always safe because it only reads state while automated remediation risks content corruption.md +42 -0
  54. package/methodology/automation should be retired when its false positive rate exceeds its true positive rate or it catches zero issues.md +56 -0
  55. package/methodology/backlinks implicitly define notes by revealing usage context.md +35 -0
  56. package/methodology/backward maintenance asks what would be different if written today.md +62 -0
  57. package/methodology/balance onboarding enforcement and questions to prevent premature complexity.md +229 -0
  58. package/methodology/basic level categorization determines optimal MOC granularity.md +51 -0
  59. package/methodology/batching by context similarity reduces switching costs in agent processing.md +43 -0
  60. package/methodology/behavioral anti-patterns matter more than tool selection.md +42 -0
  61. package/methodology/betweenness centrality identifies bridge notes connecting disparate knowledge domains.md +57 -0
  62. package/methodology/blueprints that teach construction outperform downloads that provide pre-built code for platform-dependent modules.md +42 -0
  63. package/methodology/bootstrapping principle enables self-improving systems.md +62 -0
  64. package/methodology/build automatic memory through cognitive offloading and session handoffs.md +285 -0
  65. package/methodology/capture the reaction to content not just the content itself.md +41 -0
  66. package/methodology/claims must be specific enough to be wrong.md +36 -0
  67. package/methodology/closure rituals create clean breaks that prevent attention residue bleed.md +44 -0
  68. package/methodology/cognitive offloading is the architectural foundation for vault design.md +46 -0
  69. package/methodology/cognitive outsourcing risk in agent-operated systems.md +55 -0
  70. package/methodology/coherence maintains consistency despite inconsistent inputs.md +96 -0
  71. package/methodology/coherent architecture emerges from wiki links spreading activation and small-world topology.md +48 -0
  72. package/methodology/community detection algorithms can inform when MOCs should split or merge.md +52 -0
  73. package/methodology/complete navigation requires four complementary types that no single mechanism provides.md +43 -0
  74. package/methodology/complex systems evolve from simple working systems.md +59 -0
  75. package/methodology/composable knowledge architecture builds systems from independent toggleable modules not monolithic templates.md +61 -0
  76. package/methodology/compose multi-domain systems through separate templates and shared graph.md +372 -0
  77. package/methodology/concept-orientation beats source-orientation for cross-domain connections.md +51 -0
  78. package/methodology/confidence thresholds gate automated action between the mechanical and judgment zones.md +50 -0
  79. package/methodology/configuration dimensions interact so choices in one create pressure on others.md +58 -0
  80. package/methodology/configuration paralysis emerges when derivation surfaces too many decisions.md +44 -0
  81. package/methodology/context files function as agent operating systems through self-referential self-extension.md +46 -0
  82. package/methodology/context phrase clarity determines how deep a navigation hierarchy can scale.md +46 -0
  83. package/methodology/continuous small-batch processing eliminates review dread.md +48 -0
  84. package/methodology/controlled disorder engineers serendipity through semantic rather than topical linking.md +51 -0
  85. package/methodology/creative writing uses worldbuilding consistency with character tracking.md +672 -0
  86. package/methodology/cross-links between MOC territories indicate creative leaps and integration depth.md +43 -0
  87. package/methodology/dangling links reveal which notes want to exist.md +62 -0
  88. package/methodology/data exit velocity measures how quickly content escapes vendor lock-in.md +74 -0
  89. package/methodology/decontextualization risk means atomicity may strip meaning that cannot be recovered.md +48 -0
  90. package/methodology/dense interlinked research claims enable derivation while sparse references only enable templating.md +47 -0
  91. package/methodology/dependency resolution through topological sort makes module composition transparent and verifiable.md +56 -0
  92. package/methodology/derivation generates knowledge systems from composable research claims not template customization.md +63 -0
  93. package/methodology/derivation-engine.md +27 -0
  94. package/methodology/derived systems follow a seed-evolve-reseed lifecycle.md +56 -0
  95. package/methodology/description quality for humans diverges from description quality for keyword search.md +73 -0
  96. package/methodology/descriptions are retrieval filters not summaries.md +112 -0
  97. package/methodology/design MOCs as attention management devices with lifecycle governance.md +318 -0
  98. package/methodology/design-dimensions.md +66 -0
  99. package/methodology/digital mutability enables note evolution that physical permanence forbids.md +54 -0
  100. package/methodology/discovery-retrieval.md +48 -0
  101. package/methodology/distinctiveness scoring treats description quality as measurable.md +69 -0
  102. package/methodology/does agent processing recover what fast capture loses.md +43 -0
  103. package/methodology/domain-compositions.md +37 -0
  104. package/methodology/dual-coding with visual elements could enhance agent traversal.md +55 -0
  105. package/methodology/each module must be describable in one sentence under 200 characters or it does too many things.md +45 -0
  106. package/methodology/each new note compounds value by creating traversal paths.md +55 -0
  107. package/methodology/eight configuration dimensions parameterize the space of possible knowledge systems.md +56 -0
  108. package/methodology/elaborative encoding is the quality gate for new notes.md +55 -0
  109. package/methodology/enforce schema with graduated strictness across capture processing and query zones.md +221 -0
  110. package/methodology/enforcing atomicity can create paralysis when ideas resist decomposition.md +43 -0
  111. package/methodology/engineering uses technical decision tracking with architectural memory.md +766 -0
  112. package/methodology/every knowledge domain shares a four-phase processing skeleton that diverges only in the process step.md +53 -0
  113. package/methodology/evolution observations provide actionable signals for system adaptation.md +67 -0
  114. package/methodology/external memory shapes cognition more than base model.md +60 -0
  115. package/methodology/faceted classification treats notes as multi-dimensional objects rather than folder contents.md +65 -0
  116. package/methodology/failure-modes.md +27 -0
  117. package/methodology/false universalism applies same processing logic regardless of domain.md +49 -0
  118. package/methodology/federated wiki pattern enables multi-agent divergence as feature not bug.md +59 -0
  119. package/methodology/flat files break at retrieval scale.md +75 -0
  120. package/methodology/forced engagement produces weak connections.md +48 -0
  121. package/methodology/four abstraction layers separate platform-agnostic from platform-dependent knowledge system features.md +47 -0
  122. package/methodology/fresh context per task preserves quality better than chaining phases.md +44 -0
  123. package/methodology/friction reveals architecture.md +63 -0
  124. package/methodology/friction-driven module adoption prevents configuration debt by adding complexity only at pain points.md +48 -0
  125. package/methodology/gardening cycle implements tend prune fertilize operations.md +41 -0
  126. package/methodology/generation effect gate blocks processing without transformation.md +40 -0
  127. package/methodology/goal-driven memory orchestration enables autonomous domain learning through directed compute allocation.md +41 -0
  128. package/methodology/good descriptions layer heuristic then mechanism then implication.md +57 -0
  129. package/methodology/graph-structure.md +65 -0
  130. package/methodology/guided notes might outperform post-hoc structuring for high-volume capture.md +37 -0
  131. package/methodology/health wellness uses symptom-trigger correlation with multi-dimensional tracking.md +819 -0
  132. package/methodology/hook composition creates emergent methodology from independent single-concern components.md +47 -0
  133. package/methodology/hook enforcement guarantees quality while instruction enforcement merely suggests it.md +51 -0
  134. package/methodology/hook-driven learning loops create self-improving methodology through observation accumulation.md +62 -0
  135. package/methodology/hooks are the agent habit system that replaces the missing basal ganglia.md +40 -0
  136. package/methodology/hooks cannot replace genuine cognitive engagement yet more automation is always tempting.md +87 -0
  137. package/methodology/hooks enable context window efficiency by delegating deterministic checks to external processes.md +47 -0
  138. package/methodology/idempotent maintenance operations are safe to automate because running them twice produces the same result as running them once.md +44 -0
  139. package/methodology/implement condition-based maintenance triggers for derived systems.md +255 -0
  140. package/methodology/implicit dependencies create distributed monoliths that fail silently across configurations.md +58 -0
  141. package/methodology/implicit knowledge emerges from traversal.md +55 -0
  142. package/methodology/incremental formalization happens through repeated touching of old notes.md +60 -0
  143. package/methodology/incremental reading enables cross-source connection finding.md +39 -0
  144. package/methodology/index.md +32 -0
  145. package/methodology/inline links carry richer relationship data than metadata fields.md +91 -0
  146. package/methodology/insight accretion differs from productivity in knowledge systems.md +41 -0
  147. package/methodology/intermediate packets enable assembly over creation.md +52 -0
  148. package/methodology/intermediate representation pattern enables reliable vault operations beyond regex.md +62 -0
  149. package/methodology/justification chains enable forward backward and evolution reasoning about configuration decisions.md +46 -0
  150. package/methodology/knowledge system architecture is parameterized by platform capabilities not fixed by methodology.md +51 -0
  151. package/methodology/knowledge systems become communication partners through complexity and memory humans cannot sustain.md +47 -0
  152. package/methodology/knowledge systems share universal operations and structural components across all methodology traditions.md +46 -0
  153. package/methodology/legal case management uses precedent chains with regulatory change propagation.md +892 -0
  154. package/methodology/live index via periodic regeneration keeps discovery current.md +58 -0
  155. package/methodology/local-first file formats are inherently agent-native.md +69 -0
  156. package/methodology/logic column pattern separates reasoning from procedure.md +35 -0
  157. package/methodology/maintenance operations are more universal than creative pipelines because structural health is domain-invariant.md +47 -0
  158. package/methodology/maintenance scheduling frequency should match consequence speed not detection capability.md +50 -0
  159. package/methodology/maintenance targeting should prioritize mechanism and theory notes.md +26 -0
  160. package/methodology/maintenance-patterns.md +72 -0
  161. package/methodology/markdown plus YAML plus ripgrep implements a queryable graph database without infrastructure.md +55 -0
  162. package/methodology/maturity field enables agent context prioritization.md +33 -0
  163. package/methodology/memory-architecture.md +27 -0
  164. package/methodology/metacognitive confidence can diverge from retrieval capability.md +42 -0
  165. package/methodology/metadata reduces entropy enabling precision over recall.md +91 -0
  166. package/methodology/methodology development should follow the trajectory from documentation to skill to hook as understanding hardens.md +80 -0
  167. package/methodology/methodology traditions are named points in a shared configuration space not competing paradigms.md +64 -0
  168. package/methodology/mnemonic medium embeds verification into navigation.md +46 -0
  169. package/methodology/module communication through shared YAML fields creates loose coupling without direct dependencies.md +44 -0
  170. package/methodology/module deactivation must account for structural artifacts that survive the toggle.md +49 -0
  171. package/methodology/multi-domain systems compose through separate templates and shared graph.md +61 -0
  172. package/methodology/multi-domain-composition.md +27 -0
  173. package/methodology/narrow folksonomy optimizes for single-operator retrieval unlike broad consensus tagging.md +53 -0
  174. package/methodology/navigation infrastructure passes through distinct scaling regimes that require qualitative strategy shifts.md +48 -0
  175. package/methodology/navigational vertigo emerges in pure association systems without local hierarchy.md +54 -0
  176. package/methodology/note titles should function as APIs enabling sentence transclusion.md +51 -0
  177. package/methodology/note-design.md +57 -0
  178. package/methodology/notes are skills /342/200/224 curated knowledge injected when relevant.md" +62 -0
  179. package/methodology/notes function as cognitive anchors that stabilize attention during complex tasks.md +41 -0
  180. package/methodology/novel domains derive by mapping knowledge type to closest reference domain then adapting.md +50 -0
  181. package/methodology/nudge theory explains graduated hook enforcement as choice architecture for agents.md +59 -0
  182. package/methodology/observation and tension logs function as dead-letter queues for failed automation.md +51 -0
  183. package/methodology/operational memory and knowledge memory serve different functions in agent architecture.md +48 -0
  184. package/methodology/operational wisdom requires contextual observation.md +52 -0
  185. package/methodology/orchestrated vault creation transforms arscontexta from tool to autonomous knowledge factory.md +40 -0
  186. package/methodology/organic emergence versus active curation creates a fundamental vault governance tension.md +68 -0
  187. package/methodology/orphan notes are seeds not failures.md +38 -0
  188. package/methodology/over-automation corrupts quality when hooks encode judgment rather than verification.md +62 -0
  189. package/methodology/people relationships uses Dunbar-layered graphs with interaction tracking.md +659 -0
  190. package/methodology/personal assistant uses life area management with review automation.md +610 -0
  191. package/methodology/platform adapter translation is semantic not mechanical because hook event meanings differ.md +40 -0
  192. package/methodology/platform capability tiers determine which knowledge system features can be implemented.md +48 -0
  193. package/methodology/platform fragmentation means identical conceptual operations require different implementations across agent environments.md +44 -0
  194. package/methodology/premature complexity is the most common derivation failure mode.md +45 -0
  195. package/methodology/prevent domain-specific failure modes through the vulnerability matrix.md +336 -0
  196. package/methodology/processing effort should follow retrieval demand.md +57 -0
  197. package/methodology/processing-workflows.md +75 -0
  198. package/methodology/product management uses feedback pipelines with experiment tracking.md +789 -0
  199. package/methodology/productivity porn risk in meta-system building.md +30 -0
  200. package/methodology/programmable notes could enable property-triggered workflows.md +64 -0
  201. package/methodology/progressive disclosure means reading right not reading less.md +69 -0
  202. package/methodology/progressive schema validates only what active modules require not the full system schema.md +49 -0
  203. package/methodology/project management uses decision tracking with stakeholder context.md +776 -0
  204. package/methodology/propositional link semantics transform wiki links from associative to reasoned.md +87 -0
  205. package/methodology/prospective memory requires externalization.md +53 -0
  206. package/methodology/provenance tracks where beliefs come from.md +62 -0
  207. package/methodology/queries evolve during search so agents should checkpoint.md +35 -0
  208. package/methodology/question-answer metadata enables inverted search patterns.md +39 -0
  209. package/methodology/random note resurfacing prevents write-only memory.md +33 -0
  210. package/methodology/reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring.md +59 -0
  211. package/methodology/reflection synthesizes existing notes into new insight.md +100 -0
  212. package/methodology/retrieval utility should drive design over capture completeness.md +69 -0
  213. package/methodology/retrieval verification loop tests description quality at scale.md +81 -0
  214. package/methodology/role field makes graph structure explicit.md +94 -0
  215. package/methodology/scaffolding enables divergence that fine-tuning cannot.md +67 -0
  216. package/methodology/schema enforcement via validation agents enables soft consistency.md +60 -0
  217. package/methodology/schema evolution follows observe-then-formalize not design-then-enforce.md +65 -0
  218. package/methodology/schema field names are the only domain specific element in the universal note pattern.md +46 -0
  219. package/methodology/schema fields should use domain-native vocabulary not abstract terminology.md +47 -0
  220. package/methodology/schema templates reduce cognitive overhead at capture time.md +55 -0
  221. package/methodology/schema validation hooks externalize inhibitory control that degrades under cognitive load.md +48 -0
  222. package/methodology/schema-enforcement.md +27 -0
  223. package/methodology/self-extension requires context files to contain platform operations knowledge not just methodology.md +47 -0
  224. package/methodology/sense-making vs storage does compression lose essential nuance.md +73 -0
  225. package/methodology/session boundary hooks implement cognitive bookends for orientation and reflection.md +60 -0
  226. package/methodology/session handoff creates continuity without persistent memory.md +43 -0
  227. package/methodology/session outputs are packets for future selves.md +43 -0
  228. package/methodology/session transcript mining enables experiential validation that structural tests cannot provide.md +38 -0
  229. package/methodology/skill context budgets constrain knowledge system complexity on agent platforms.md +52 -0
  230. package/methodology/skills encode methodology so manual execution bypasses quality gates.md +50 -0
  231. package/methodology/small-world topology requires hubs and dense local links.md +99 -0
  232. package/methodology/source attribution enables tracing claims to foundations.md +38 -0
  233. package/methodology/spaced repetition scheduling could optimize vault maintenance.md +44 -0
  234. package/methodology/spreading activation models how agents should traverse.md +79 -0
  235. package/methodology/stale navigation actively misleads because agents trust curated maps completely.md +43 -0
  236. package/methodology/stigmergy coordinates agents through environmental traces without direct communication.md +62 -0
  237. package/methodology/storage versus thinking distinction determines which tool patterns apply.md +56 -0
  238. package/methodology/structure enables navigation without reading everything.md +52 -0
  239. package/methodology/structure without processing provides no value.md +56 -0
  240. package/methodology/student learning uses prerequisite graphs with spaced retrieval.md +770 -0
  241. package/methodology/summary coherence tests composability before filing.md +37 -0
  242. package/methodology/tag rot applies to wiki links because titles serve as both identifier and display text.md +50 -0
  243. package/methodology/temporal media must convert to spatial text for agent traversal.md +43 -0
  244. package/methodology/temporal processing priority creates age-based inbox urgency.md +45 -0
  245. package/methodology/temporal separation of capture and processing preserves context freshness.md +39 -0
  246. package/methodology/ten universal primitives form the kernel of every viable agent knowledge system.md +162 -0
  247. package/methodology/testing effect could enable agent knowledge verification.md +38 -0
  248. package/methodology/the AgentSkills standard embodies progressive disclosure at the skill level.md +40 -0
  249. package/methodology/the derivation engine improves recursively as deployed systems generate observations.md +49 -0
  250. package/methodology/the determinism boundary separates hook methodology from skill methodology.md +46 -0
  251. package/methodology/the fix-versus-report decision depends on determinism reversibility and accumulated trust.md +45 -0
  252. package/methodology/the generation effect requires active transformation not just storage.md +57 -0
  253. package/methodology/the no wrong patches guarantee ensures any valid module combination produces a valid system.md +58 -0
  254. package/methodology/the system is the argument.md +46 -0
  255. package/methodology/the vault constitutes identity for agents.md +86 -0
  256. package/methodology/the vault methodology transfers because it encodes cognitive science not domain specifics.md +47 -0
  257. package/methodology/therapy journal uses warm personality with pattern detection for emotional processing.md +584 -0
  258. package/methodology/three capture schools converge through agent-mediated synthesis.md +55 -0
  259. package/methodology/three concurrent maintenance loops operate at different timescales to catch different classes of problems.md +56 -0
  260. package/methodology/throughput matters more than accumulation.md +58 -0
  261. package/methodology/title as claim enables traversal as reasoning.md +50 -0
  262. package/methodology/topological organization beats temporal for knowledge work.md +52 -0
  263. package/methodology/trading uses conviction tracking with thesis-outcome correlation.md +699 -0
  264. package/methodology/trails transform ephemeral navigation into persistent artifacts.md +39 -0
  265. package/methodology/transform universal vocabulary to domain-native language through six levels.md +259 -0
  266. package/methodology/type field enables structured queries without folder hierarchies.md +53 -0
  267. package/methodology/use-case presets dissolve the tension between composability and simplicity.md +44 -0
  268. package/methodology/vault conventions may impose hidden rigidity on thinking.md +44 -0
  269. package/methodology/verbatim risk applies to agents too.md +31 -0
  270. package/methodology/vibe notetaking is the emerging industry consensus for AI-native self-organization.md +56 -0
  271. package/methodology/vivid memories need verification.md +45 -0
  272. package/methodology/vocabulary-transformation.md +27 -0
  273. package/methodology/voice capture is the highest-bandwidth channel for agent-delegated knowledge systems.md +45 -0
  274. package/methodology/wiki links are the digital evolution of analog indexing.md +73 -0
  275. package/methodology/wiki links as social contract transforms agents into stewards of incomplete references.md +52 -0
  276. package/methodology/wiki links create navigation paths that shape retrieval.md +63 -0
  277. package/methodology/wiki links implement GraphRAG without the infrastructure.md +101 -0
  278. package/methodology/writing for audience blocks authentic creation.md +22 -0
  279. package/methodology/you operate a system that takes notes.md +79 -0
  280. package/openclaw/SKILL.md +110 -0
  281. package/package.json +45 -0
  282. package/platforms/README.md +51 -0
  283. package/platforms/claude-code/generator.md +61 -0
  284. package/platforms/claude-code/hooks/README.md +186 -0
  285. package/platforms/claude-code/hooks/auto-commit.sh.template +38 -0
  286. package/platforms/claude-code/hooks/session-capture.sh.template +72 -0
  287. package/platforms/claude-code/hooks/session-orient.sh.template +189 -0
  288. package/platforms/claude-code/hooks/write-validate.sh.template +106 -0
  289. package/platforms/openclaw/generator.md +82 -0
  290. package/platforms/openclaw/hooks/README.md +89 -0
  291. package/platforms/openclaw/hooks/bootstrap.ts.template +224 -0
  292. package/platforms/openclaw/hooks/command-new.ts.template +165 -0
  293. package/platforms/openclaw/hooks/heartbeat.ts.template +214 -0
  294. package/platforms/shared/features/README.md +70 -0
  295. package/platforms/shared/skill-blocks/graph.md +145 -0
  296. package/platforms/shared/skill-blocks/learn.md +119 -0
  297. package/platforms/shared/skill-blocks/next.md +131 -0
  298. package/platforms/shared/skill-blocks/pipeline.md +326 -0
  299. package/platforms/shared/skill-blocks/ralph.md +616 -0
  300. package/platforms/shared/skill-blocks/reduce.md +1142 -0
  301. package/platforms/shared/skill-blocks/refactor.md +129 -0
  302. package/platforms/shared/skill-blocks/reflect.md +780 -0
  303. package/platforms/shared/skill-blocks/remember.md +524 -0
  304. package/platforms/shared/skill-blocks/rethink.md +574 -0
  305. package/platforms/shared/skill-blocks/reweave.md +680 -0
  306. package/platforms/shared/skill-blocks/seed.md +320 -0
  307. package/platforms/shared/skill-blocks/stats.md +145 -0
  308. package/platforms/shared/skill-blocks/tasks.md +171 -0
  309. package/platforms/shared/skill-blocks/validate.md +323 -0
  310. package/platforms/shared/skill-blocks/verify.md +562 -0
  311. package/platforms/shared/templates/README.md +35 -0
  312. package/presets/experimental/categories.yaml +1 -0
  313. package/presets/experimental/preset.yaml +38 -0
  314. package/presets/experimental/starter/README.md +7 -0
  315. package/presets/experimental/vocabulary.yaml +7 -0
  316. package/presets/personal/categories.yaml +7 -0
  317. package/presets/personal/preset.yaml +41 -0
  318. package/presets/personal/starter/goals.md +21 -0
  319. package/presets/personal/starter/index.md +17 -0
  320. package/presets/personal/starter/life-areas.md +21 -0
  321. package/presets/personal/starter/people.md +21 -0
  322. package/presets/personal/vocabulary.yaml +32 -0
  323. package/presets/research/categories.yaml +8 -0
  324. package/presets/research/preset.yaml +41 -0
  325. package/presets/research/starter/index.md +17 -0
  326. package/presets/research/starter/methods.md +21 -0
  327. package/presets/research/starter/open-questions.md +21 -0
  328. package/presets/research/vocabulary.yaml +33 -0
  329. package/reference/AUDIT-REPORT.md +238 -0
  330. package/reference/claim-map.md +172 -0
  331. package/reference/components.md +327 -0
  332. package/reference/conversation-patterns.md +542 -0
  333. package/reference/derivation-validation.md +649 -0
  334. package/reference/dimension-claim-map.md +134 -0
  335. package/reference/evolution-lifecycle.md +297 -0
  336. package/reference/failure-modes.md +235 -0
  337. package/reference/interaction-constraints.md +204 -0
  338. package/reference/kernel.yaml +242 -0
  339. package/reference/methodology.md +283 -0
  340. package/reference/open-questions.md +279 -0
  341. package/reference/personality-layer.md +302 -0
  342. package/reference/self-space.md +299 -0
  343. package/reference/semantic-vs-keyword.md +288 -0
  344. package/reference/session-lifecycle.md +298 -0
  345. package/reference/templates/base-note.md +16 -0
  346. package/reference/templates/companion-note.md +70 -0
  347. package/reference/templates/creative-note.md +16 -0
  348. package/reference/templates/learning-note.md +16 -0
  349. package/reference/templates/life-note.md +16 -0
  350. package/reference/templates/moc.md +26 -0
  351. package/reference/templates/relationship-note.md +17 -0
  352. package/reference/templates/research-note.md +19 -0
  353. package/reference/templates/session-log.md +24 -0
  354. package/reference/templates/therapy-note.md +16 -0
  355. package/reference/test-fixtures/edge-case-constraints.md +148 -0
  356. package/reference/test-fixtures/multi-domain.md +164 -0
  357. package/reference/test-fixtures/novel-domain-gaming.md +138 -0
  358. package/reference/test-fixtures/research-minimal.md +102 -0
  359. package/reference/test-fixtures/therapy-full.md +155 -0
  360. package/reference/testing-milestones.md +1087 -0
  361. package/reference/three-spaces.md +363 -0
  362. package/reference/tradition-presets.md +203 -0
  363. package/reference/use-case-presets.md +341 -0
  364. package/reference/validate-kernel.sh +432 -0
  365. package/reference/vocabulary-transforms.md +85 -0
  366. package/scripts/sync-thinking.sh +147 -0
  367. package/skill-sources/graph/SKILL.md +567 -0
  368. package/skill-sources/graph/skill.json +17 -0
  369. package/skill-sources/learn/SKILL.md +254 -0
  370. package/skill-sources/learn/skill.json +17 -0
  371. package/skill-sources/next/SKILL.md +407 -0
  372. package/skill-sources/next/skill.json +17 -0
  373. package/skill-sources/pipeline/SKILL.md +314 -0
  374. package/skill-sources/pipeline/skill.json +17 -0
  375. package/skill-sources/ralph/SKILL.md +604 -0
  376. package/skill-sources/ralph/skill.json +17 -0
  377. package/skill-sources/reduce/SKILL.md +1113 -0
  378. package/skill-sources/reduce/skill.json +17 -0
  379. package/skill-sources/refactor/SKILL.md +448 -0
  380. package/skill-sources/refactor/skill.json +17 -0
  381. package/skill-sources/reflect/SKILL.md +747 -0
  382. package/skill-sources/reflect/skill.json +17 -0
  383. package/skill-sources/remember/SKILL.md +534 -0
  384. package/skill-sources/remember/skill.json +17 -0
  385. package/skill-sources/rethink/SKILL.md +658 -0
  386. package/skill-sources/rethink/skill.json +17 -0
  387. package/skill-sources/reweave/SKILL.md +657 -0
  388. package/skill-sources/reweave/skill.json +17 -0
  389. package/skill-sources/seed/SKILL.md +303 -0
  390. package/skill-sources/seed/skill.json +17 -0
  391. package/skill-sources/stats/SKILL.md +371 -0
  392. package/skill-sources/stats/skill.json +17 -0
  393. package/skill-sources/tasks/SKILL.md +402 -0
  394. package/skill-sources/tasks/skill.json +17 -0
  395. package/skill-sources/validate/SKILL.md +310 -0
  396. package/skill-sources/validate/skill.json +17 -0
  397. package/skill-sources/verify/SKILL.md +532 -0
  398. package/skill-sources/verify/skill.json +17 -0
  399. package/skills/add-domain/SKILL.md +441 -0
  400. package/skills/add-domain/skill.json +17 -0
  401. package/skills/architect/SKILL.md +568 -0
  402. package/skills/architect/skill.json +17 -0
  403. package/skills/ask/SKILL.md +388 -0
  404. package/skills/ask/skill.json +17 -0
  405. package/skills/health/SKILL.md +760 -0
  406. package/skills/health/skill.json +17 -0
  407. package/skills/help/SKILL.md +348 -0
  408. package/skills/help/skill.json +17 -0
  409. package/skills/recommend/SKILL.md +553 -0
  410. package/skills/recommend/skill.json +17 -0
  411. package/skills/reseed/SKILL.md +385 -0
  412. package/skills/reseed/skill.json +17 -0
  413. package/skills/setup/SKILL.md +1688 -0
  414. package/skills/setup/skill.json +17 -0
  415. package/skills/tutorial/SKILL.md +496 -0
  416. package/skills/tutorial/skill.json +17 -0
  417. package/skills/upgrade/SKILL.md +395 -0
  418. package/skills/upgrade/skill.json +17 -0
@@ -0,0 +1,568 @@
1
+ ---
2
+ name: architect
3
+ description: Research-backed evolution advice for your knowledge system. Analyzes health reports, friction patterns, and derivation history to propose specific changes with research justification. Never auto-implements — proposals require your approval.
4
+ version: "1.0"
5
+ generated_from: "arscontexta-v1.6"
6
+ user-invocable: true
7
+ context: fork
8
+ model: opus
9
+ allowed-tools: Read, Write, Edit, Grep, Glob, Bash, mcp__qmd__search, mcp__qmd__vsearch, mcp__qmd__query, mcp__qmd__get
10
+ argument-hint: "[optional: specific area to focus on, e.g. 'schema', 'processing', 'MOC structure']"
11
+ ---
12
+
13
+ ## Runtime Configuration (Step 0 — before any processing)
14
+
15
+ Read these files to configure domain-specific behavior:
16
+
17
+ 1. **`ops/derivation-manifest.md`** — vocabulary mapping, platform hints
18
+ - Use `vocabulary.notes` for the notes folder name
19
+ - Use `vocabulary.note` / `vocabulary.note_plural` for note type references
20
+ - Use `vocabulary.topic_map` / `vocabulary.topic_map_plural` for MOC references
21
+ - Use `vocabulary.inbox` for the inbox folder name
22
+ - Use `vocabulary.cmd_reflect` for connection-finding command name
23
+ - Use `vocabulary.cmd_reweave` for backward-pass command name
24
+ - Use `vocabulary.cmd_verify` for verification command name
25
+ - Use `vocabulary.architect` for the command name in output
26
+
27
+ 2. **`ops/config.yaml`** — processing depth, pipeline chaining, automation settings
28
+
29
+ 3. **`ops/derivation.md`** — original derivation record (the design intent baseline)
30
+
31
+ If these files don't exist, use universal defaults and warn the user.
32
+
33
+ ---
34
+
35
+ ## EXECUTE NOW
36
+
37
+ **Target: $ARGUMENTS**
38
+
39
+ Parse immediately:
40
+ - If target names a specific area (e.g., "schema", "processing", "MOC structure"): focus analysis on that area
41
+ - If target is empty: run full-system analysis across all dimensions
42
+ - If target is `--dry-run`: run analysis but do not offer implementation
43
+
44
+ **Execute these phases sequentially:**
45
+
46
+ 1. Locate system files and detect platform
47
+ 2. Read derivation record for design intent
48
+ 3. Analyze health data (recent report or live check)
49
+ 4. Scan for friction patterns across operational surfaces
50
+ 5. Consult research to ground evidence in specific claims
51
+ 6. Generate 3-5 ranked recommendations with full evidence chains
52
+ 7. Present to user and implement on approval
53
+
54
+ **START NOW.** Reference below defines the seven-phase workflow.
55
+
56
+ ---
57
+
58
+ ## Philosophy
59
+
60
+ **Evidence beats intuition. Research beats habit.**
61
+
62
+ 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.
63
+
64
+ 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.
65
+
66
+ **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.
67
+
68
+ **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.
69
+
70
+ ---
71
+
72
+ ## PHASE 1: Locate
73
+
74
+ Automated. No user interaction needed.
75
+
76
+ Detect the platform and find the system's key files:
77
+
78
+ ```
79
+ Check filesystem:
80
+ .claude/ directory exists -> platform = "claude-code"
81
+ SOUL.md or AGENTS.md exists -> platform = "openclaw"
82
+ Neither -> platform = "minimal"
83
+ ```
84
+
85
+ Locate these files (paths vary by platform and domain vocabulary):
86
+
87
+ | File Type | What To Find | Typical Locations |
88
+ |-----------|-------------|-------------------|
89
+ | Context file | System methodology and rules | CLAUDE.md, SOUL.md + AGENTS.md, README.md |
90
+ | Self space | Agent identity and memory | self/identity.md, self/methodology.md, self/goals.md |
91
+ | Ops directory | Operational infrastructure | ops/derivation.md, ops/config.yaml, ops/sessions/, ops/observations/, ops/health/ |
92
+ | Notes directory | Primary knowledge directory | {vocabulary.notes}/ (may be domain-named: reflections/, concepts/, etc.) |
93
+ | Queue system | Pipeline state | ops/queue/queue.yaml or ops/queue/queue.json |
94
+ | Templates | Note schemas | ops/templates/ or templates/ |
95
+ | Methodology | Learned patterns | ops/methodology/ |
96
+
97
+ **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."
98
+
99
+ **If `ops/config.yaml` does not exist:** Warn: "No config file found. Using observed behavior to infer current configuration."
100
+
101
+ Record all file locations for use in subsequent phases.
102
+
103
+ ---
104
+
105
+ ## PHASE 2: Read Derivation
106
+
107
+ Read `ops/derivation.md` to understand the system's original design intent. This is the baseline against which drift is measured.
108
+
109
+ **Extract from derivation:**
110
+
111
+ | Element | What To Look For | Why It Matters |
112
+ |---------|-----------------|----------------|
113
+ | Dimension positions | The 8 configuration dimensions and their derived values | Baseline for drift detection |
114
+ | Conversation signals | What the user said that drove each choice | Understanding original intent |
115
+ | Personality | Warmth, formality, opinionatedness, emotional awareness | Voice consistency check |
116
+ | Vocabulary mapping | Universal-to-domain term translations | Output must use domain language |
117
+ | Coherence validation | What constraints were active at derivation time | Know which constraints to re-check |
118
+ | Failure mode risks | Which failure modes were flagged as HIGH risk | Prioritize monitoring these |
119
+
120
+ Also read `ops/config.yaml` — this is the live operational config that may have drifted from derivation. Compare dimension positions between derivation and config:
121
+
122
+ ```
123
+ For each of the 8 dimensions:
124
+ derivation_value = [from ops/derivation.md]
125
+ config_value = [from ops/config.yaml]
126
+ drifted = derivation_value != config_value
127
+ ```
128
+
129
+ Record any drift for Phase 6. Drift is not inherently bad — it may represent healthy evolution. But UNRECOGNIZED drift creates incoherence.
130
+
131
+ 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.
132
+
133
+ ---
134
+
135
+ ## PHASE 3: Health Analysis
136
+
137
+ Check for a recent health report in `ops/health/`:
138
+
139
+ ```bash
140
+ # Find health reports from the last 7 days
141
+ find ops/health/ -name "*.md" -mtime -7 2>/dev/null | sort -r | head -1
142
+ ```
143
+
144
+ **If a recent report exists:** Read it fully. Extract every FAIL and WARN item as structured evidence:
145
+
146
+ ```
147
+ For each FAIL/WARN:
148
+ category: [schema | orphan | link | description | stale | moc | boundary | throughput]
149
+ severity: [FAIL | WARN]
150
+ detail: [specific finding — which notes, which fields, which links]
151
+ count: [how many instances]
152
+ ```
153
+
154
+ **If no recent report exists:** Run a live health assessment. Check each category:
155
+
156
+ | Category | How to Check | FAIL Threshold | WARN Threshold |
157
+ |----------|-------------|---------------|----------------|
158
+ | Schema compliance | `grep -rL '^description:' {vocabulary.notes}/*.md` | N/A | Any note missing required fields |
159
+ | Orphan detection | Notes with zero incoming wiki-links (scan for `[[filename]]` across all notes) | N/A | Any orphan |
160
+ | Link health | Wiki-links pointing to non-existent files | Any dangling link | N/A |
161
+ | Three-space boundaries | Content in wrong space (notes in ops/, operational files in notes/) | N/A | Any violation |
162
+ | Processing throughput | Count inbox items vs notes count | >3:1 ratio | >2:1 ratio |
163
+ | Stale notes | Notes with <2 incoming links AND not modified in last 30 days | N/A | >15% of notes |
164
+ | MOC coherence | Note count per MOC | N/A | >40 notes (split candidate) or <5 (merge candidate) |
165
+ | Description quality | Descriptions that restate the title without adding information | N/A | Any restatement |
166
+
167
+ **Live check implementation:**
168
+
169
+ ```bash
170
+ # Count total notes
171
+ NOTE_COUNT=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')
172
+
173
+ # Find orphans (notes with no incoming links)
174
+ for f in {vocabulary.notes}/*.md; do
175
+ NAME=$(basename "$f" .md)
176
+ LINKS=$(grep -rl "\[\[$NAME\]\]" {vocabulary.notes}/ 2>/dev/null | wc -l | tr -d ' ')
177
+ [[ "$LINKS" -eq 0 ]] && echo "ORPHAN: $NAME"
178
+ done
179
+
180
+ # Find dangling links
181
+ grep -ohP '\[\[([^\]]+)\]\]' {vocabulary.notes}/*.md | sort -u | while read -r link; do
182
+ NAME=$(echo "$link" | sed 's/\[\[//;s/\]\]//')
183
+ [[ ! -f "{vocabulary.notes}/$NAME.md" ]] && echo "DANGLING: $NAME"
184
+ done
185
+
186
+ # Count inbox items
187
+ INBOX_COUNT=$(ls -1 {vocabulary.inbox}/ 2>/dev/null | wc -l | tr -d ' ')
188
+
189
+ # MOC sizes
190
+ grep -rl '^type: moc' {vocabulary.notes}/*.md 2>/dev/null | while read -r moc; do
191
+ COUNT=$(grep -c '^\- \[\[' "$moc" 2>/dev/null)
192
+ echo "MOC: $(basename "$moc" .md) = $COUNT notes"
193
+ done
194
+
195
+ # Missing descriptions
196
+ grep -rL '^description:' {vocabulary.notes}/*.md 2>/dev/null
197
+ ```
198
+
199
+ Record all findings as evidence for Phase 6. Every finding must include the specific notes, links, or fields affected — not just counts.
200
+
201
+ ---
202
+
203
+ ## PHASE 4: Read Friction
204
+
205
+ Scan for friction patterns across multiple operational surfaces. Friction is the gap between how the system should work and how it actually works.
206
+
207
+ ### 4a. Observation Notes
208
+
209
+ ```bash
210
+ # Find all pending observations
211
+ grep -rl '^status: pending' ops/observations/ 2>/dev/null
212
+ ```
213
+
214
+ Read each pending observation. Categorize by type:
215
+
216
+ | Category | Signal | Evidence Value |
217
+ |----------|--------|---------------|
218
+ | Friction | "this was harder than it should be" | High — points to workflow mismatch |
219
+ | Process Gap | "there is no way to do X" | High — missing capability |
220
+ | Surprise | "I did not expect this behavior" | Medium — misaligned expectations |
221
+ | Methodology | "I learned that X works better" | Medium — operational insight |
222
+ | Quality | "the output was not good enough" | High — quality gate failure |
223
+
224
+ Count occurrences per category. 3+ items in the same category = a friction pattern worth investigating.
225
+
226
+ ### 4b. Methodology Notes
227
+
228
+ ```bash
229
+ # Read all methodology notes
230
+ ls ops/methodology/*.md 2>/dev/null
231
+ ```
232
+
233
+ Read each methodology note. Look for:
234
+ - Recurring themes across multiple notes
235
+ - Tensions between stated methodology and actual practice
236
+ - Behavioral corrections that suggest the original design was wrong
237
+ - Methodology notes with multiple evidence entries (strong signal)
238
+
239
+ ### 4c. Session Logs
240
+
241
+ ```bash
242
+ # Read recent session logs (last 5-10 sessions)
243
+ ls -t ops/sessions/*.md 2>/dev/null | head -10
244
+ ```
245
+
246
+ Scan session logs for:
247
+ - Repeated complaints or workarounds
248
+ - Steps that get skipped consistently
249
+ - Patterns in what the agent does vs what the system recommends
250
+ - Error patterns or tool failures
251
+
252
+ ### 4d. Self Space
253
+
254
+ If self/ exists, read:
255
+ - `self/methodology.md` — how the agent describes its own process
256
+ - `self/goals.md` — whether current priorities align with system capabilities
257
+ - `self/memory/` — any notes about workflow frustrations
258
+
259
+ ### 4e. Build Friction Inventory
260
+
261
+ Compile all friction evidence into a structured inventory:
262
+
263
+ ```
264
+ Friction Inventory:
265
+ 1. [category]: [description]
266
+ Frequency: [N observations across M sessions]
267
+ Sources: [filenames]
268
+ Impact: [what breaks or degrades]
269
+ System area: [which dimension/skill/workflow affected]
270
+
271
+ 2. [category]: [description]
272
+ ...
273
+ ```
274
+
275
+ Rank by frequency * impact. The most frequent, highest-impact friction patterns get priority in Phase 6.
276
+
277
+ ---
278
+
279
+ ## PHASE 5: Consult Research
280
+
281
+ Ground the evidence in research. This is what separates /architect from ad-hoc troubleshooting — every recommendation connects to specific research claims, not general intuition.
282
+
283
+ Read the reference files:
284
+
285
+ | Reference | What It Contains | When To Use |
286
+ |-----------|-----------------|-------------|
287
+ | `${CLAUDE_PLUGIN_ROOT}/reference/dimension-claim-map.md` | Which research claims inform which dimensions | Mapping friction to dimension adjustments |
288
+ | `${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md` | How dimension choices create pressure on others | Cascade analysis for proposed changes |
289
+ | `${CLAUDE_PLUGIN_ROOT}/reference/methodology.md` | Universal principles and processing pipeline | Grounding recommendations in first principles |
290
+ | `${CLAUDE_PLUGIN_ROOT}/reference/failure-modes.md` | 10 failure modes with domain vulnerability matrix | Connecting friction to known failure patterns |
291
+ | `${CLAUDE_PLUGIN_ROOT}/reference/tradition-presets.md` | Named points in configuration space | Alternative configurations to consider |
292
+ | `${CLAUDE_PLUGIN_ROOT}/reference/vocabulary-transforms.md` | Universal-to-domain term mapping | Ensuring output uses domain vocabulary |
293
+ | `${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md` | Self/notes/ops architecture and boundary rules | Three-space boundary analysis |
294
+ | `${CLAUDE_PLUGIN_ROOT}/reference/derivation-validation.md` | Validation tests for derived systems | Post-change validation criteria |
295
+ | `${CLAUDE_PLUGIN_ROOT}/reference/evolution-lifecycle.md` | Seed-evolve-reseed patterns, friction-driven adoption | When to evolve vs when to reseed |
296
+ | `${CLAUDE_PLUGIN_ROOT}/reference/self-space.md` | Agent identity generation and self/ architecture | Self-space related recommendations |
297
+
298
+ ### Research Matching Process
299
+
300
+ For each friction pattern or health issue identified in Phases 3-4:
301
+
302
+ **Step 1: Check dimension-claim-map.md**
303
+ - Which research claims relate to this issue?
304
+ - What dimension positions do those claims support?
305
+ - Does the current configuration conflict with what research recommends?
306
+
307
+ **Step 2: Check interaction-constraints.md**
308
+ - Is this friction a CASCADE effect from a dimension mismatch?
309
+ - Would changing one dimension to fix this create pressure on another?
310
+ - Are there compensating mechanisms documented?
311
+
312
+ **Step 3: Check failure-modes.md**
313
+ - Does this match a known failure mode pattern?
314
+ - Was this failure mode flagged as HIGH risk during derivation?
315
+ - What does the failure mode document say about mitigation?
316
+
317
+ **Step 4: Search the knowledge graph**
318
+ - Use `mcp__qmd__query` to find claims that address the specific friction
319
+ - Fall back to `mcp__qmd__vsearch` if hybrid search is unavailable
320
+ - Fall back to reading bundled reference files directly if MCP is entirely unavailable
321
+ - Search for the friction pattern described in natural language
322
+ - Search for the system area affected
323
+ - Search for proposed solution concepts
324
+
325
+ ```
326
+ mcp__qmd__query query="[friction description in natural language]" limit=10
327
+ ```
328
+
329
+ Read the top results. For each relevant claim:
330
+ - Note the claim title (for citation in recommendations)
331
+ - Note what the claim argues
332
+ - Note how it applies to the current friction
333
+
334
+ **The goal is to connect EVERY recommendation to specific research, not general intuition.**
335
+
336
+ ---
337
+
338
+ ## PHASE 6: Generate Recommendations
339
+
340
+ Synthesize evidence from Phases 2-5 into 3-5 concrete recommendations, ranked by impact-to-effort ratio.
341
+
342
+ ### Ranking Criteria
343
+
344
+ | Criterion | Scale | What It Measures |
345
+ |-----------|-------|-----------------|
346
+ | Impact | high / medium / low | How much does this improve the system? |
347
+ | Effort | minutes / hours / days | How much work to implement? |
348
+ | Risk | reversible / partially reversible / irreversible | What could go wrong? |
349
+ | Evidence strength | strong (5+ data points) / moderate (3-4) / speculative (1-2) | How much supporting evidence? |
350
+
351
+ **Limit to 3-5 recommendations.** More than 5 creates decision paralysis. If you found more issues, prioritize ruthlessly — the rest can wait for the next /architect pass.
352
+
353
+ ### Priority Ordering
354
+
355
+ 1. **FAIL items from health** — these are broken, fix first
356
+ 2. **High-frequency friction patterns** — recurring pain, address next
357
+ 3. **Drift corrections** — config diverged from derivation without rationale
358
+ 4. **Research-backed optimizations** — improvements supported by strong evidence
359
+ 5. **Speculative improvements** — interesting ideas with thin evidence (include at most 1)
360
+
361
+ ### Implementation Time Estimation
362
+
363
+ Every recommendation MUST include a concrete time estimate:
364
+
365
+ | Effort Level | Typical Changes | Estimated Time |
366
+ |-------------|----------------|----------------|
367
+ | minutes | Config value change, template field addition, single file edit | 5-15 minutes |
368
+ | hours | Skill regeneration, MOC restructuring, schema migration | 30-120 minutes |
369
+ | days | Full reseed, architecture change, multi-skill redesign | Multiple sessions |
370
+
371
+ **Apply the 25% budget rule:** If the estimated implementation time exceeds 25% of a typical session (>15 minutes for a 60-minute session), recommend deferring to next session unless the issue is a FAIL-level health problem.
372
+
373
+ ### Recommendation Format
374
+
375
+ For each recommendation, construct the full analysis:
376
+
377
+ ```
378
+ ### [N]. [Specific change title]
379
+
380
+ **What:** [Concrete change — specific enough to implement without further clarification.
381
+ Name the exact file, section, and value that changes.]
382
+
383
+ **Why:** [Evidence chain from health analysis + friction patterns]
384
+ - Health: [specific FAIL/WARN from Phase 3, with note names/counts]
385
+ - Friction: [specific patterns from Phase 4, with observation filenames]
386
+
387
+ **Research:** [Specific claims supporting this change]
388
+ - From dimension-claim-map: [claim title and what it argues]
389
+ - From knowledge graph: [related claims found via search, with titles]
390
+ - From failure-modes: [if this matches a documented failure mode]
391
+
392
+ **Interaction effects:** [Cascade analysis from interaction-constraints.md]
393
+ - Changing [dimension X] from [current] to [proposed] creates pressure on [dimension Y]
394
+ - Compensating mechanism: [how to handle the cascade, or "none needed"]
395
+ - If no interaction effects: "No cascade effects detected for this change."
396
+
397
+ **Impact:** [effort] effort / [benefit] benefit / [risk] risk
398
+ **Estimated implementation time:** ~X minutes
399
+ **Expected benefit:** [Measurable outcome the user can verify]
400
+ **Recommendation:** implement now / defer to next session
401
+ **Reversible:** [yes / no / partially — with explanation]
402
+
403
+ **Steps:**
404
+ 1. [First concrete step — exact file and change]
405
+ 2. [Second concrete step]
406
+ 3. [Update ops/derivation.md with change rationale]
407
+ 4. [Run validation to confirm nothing broke]
408
+ ```
409
+
410
+ ### Quality Gates for Recommendations
411
+
412
+ Every recommendation MUST have:
413
+
414
+ 1. **Specific file references** — not "update the context file" but "update CLAUDE.md, section 'Processing Pipeline', line ~150"
415
+ 2. **Evidence backing** — at least 2 data points (health finding + friction observation, or 2+ friction observations)
416
+ 3. **Research citation** — at least 1 specific claim from the knowledge base
417
+ 4. **Risk awareness** — what could go wrong, stated explicitly
418
+ 5. **Reversibility assessment** — can this be undone if it makes things worse?
419
+ 6. **Time estimate** — concrete, not vague
420
+ 7. **Implementation steps** — ordered, each step references exact files
421
+
422
+ **Reject recommendations that fail any of these gates.** Thin recommendations erode trust. Better to present 2 strong recommendations than 5 weak ones.
423
+
424
+ ---
425
+
426
+ ## PHASE 7: Present to User
427
+
428
+ Present the ranked recommendations. Use the user's domain vocabulary (from derivation.md vocabulary mapping) throughout — never expose universal terms to a domain user.
429
+
430
+ ### Output Format
431
+
432
+ ```
433
+ === ARCHITECT REPORT ===
434
+ System: [domain name from derivation]
435
+ Platform: [detected platform]
436
+ Focus: [specific area if requested, or "full system"]
437
+ Date: [YYYY-MM-DD]
438
+
439
+ Evidence Summary:
440
+ Health: [N FAIL, N WARN, N PASS — from Phase 3]
441
+ Friction: [top 3 friction patterns with frequency counts]
442
+ Drift: [dimensions that shifted from derivation, if any, or "none detected"]
443
+ Failure modes: [HIGH-risk modes from derivation that show activity, or "none active"]
444
+
445
+ --- Recommendations (ranked by impact-to-effort) ---
446
+
447
+ [Recommendation 1 — full format from Phase 6]
448
+
449
+ [Recommendation 2 — full format from Phase 6]
450
+
451
+ [Recommendation 3 — full format from Phase 6]
452
+
453
+ [Optional: Recommendations 4-5]
454
+
455
+ --- Next Steps ---
456
+ Which recommendations would you like to implement? I will execute the steps
457
+ and update ops/derivation.md with the rationale.
458
+
459
+ Options:
460
+ - "all" — implement all recommendations
461
+ - "1, 3" — implement specific recommendations
462
+ - "none" — defer all to next session
463
+ - "explain 2" — get more detail on a specific recommendation
464
+ === END REPORT ===
465
+ ```
466
+
467
+ ### On User Approval
468
+
469
+ Implement the selected recommendations following the steps listed. For each implementation:
470
+
471
+ 1. **Make the change** — edit the specific files as described in Steps
472
+ 2. **Show before/after** for non-trivial changes (section replacements, config changes)
473
+ 3. **Update `ops/derivation.md`** with:
474
+ - What changed
475
+ - Why (evidence summary — health findings + friction patterns)
476
+ - Research backing (claim references from knowledge base)
477
+ - Date of change
478
+ - Interaction effects noted (if any)
479
+ 4. **Log to `ops/changelog.md`** (create if missing):
480
+ ```markdown
481
+ ## YYYY-MM-DD: [change title]
482
+
483
+ **Source:** /architect — [evidence summary]
484
+ **Change:** [what was modified, which files]
485
+ **Research:** [supporting claims]
486
+ **Risk:** [risk assessment]
487
+ ```
488
+ 5. **Run post-change validation:**
489
+ - All wiki links still resolve
490
+ - All notes still have required schema fields
491
+ - MOC hierarchy intact
492
+ - No three-space boundary violations introduced
493
+ - Session orient still loads correctly
494
+
495
+ Report validation results:
496
+ ```
497
+ Implementation complete.
498
+ Changed: [list of files modified]
499
+ Validation: [N]/[N] checks PASS
500
+ [Any warnings or issues]
501
+ ```
502
+
503
+ ### On Rejection
504
+
505
+ - Do not re-propose the same change without new evidence
506
+ - Optionally ask why — capture the reasoning as a new observation if it reveals design philosophy
507
+ - Mark the recommendation as "considered and deferred" — do not keep re-surfacing it
508
+
509
+ ### When Evidence Suggests /reseed
510
+
511
+ If analysis reveals:
512
+ - Dimension incoherence across >3 dimensions
513
+ - Vocabulary no longer matches user's actual language
514
+ - Three-space boundaries dissolved
515
+ - Template divergence >40%
516
+
517
+ Then recommend /reseed instead of incremental patches:
518
+ ```
519
+ NOTICE: The evidence suggests systemic drift across multiple dimensions.
520
+ Incremental patching may create more incoherence. Consider running /reseed
521
+ for a principled re-derivation from first principles.
522
+
523
+ Drift detected in: [list dimensions]
524
+ Evidence: [key observations]
525
+ ```
526
+
527
+ ---
528
+
529
+ ## Edge Cases
530
+
531
+ ### No ops/derivation.md
532
+
533
+ Recommendations based on current state analysis only. Note in report: "Without derivation history, recommendations cannot assess drift or design intent. Consider running /reseed to establish a derivation baseline."
534
+
535
+ ### No ops/observations/ or ops/sessions/
536
+
537
+ Friction analysis is limited. Note: "No operational friction data available. Recommendations based on health analysis and research only. Begin capturing observations during work to enable friction-based evolution."
538
+
539
+ ### Small Vault (<10 notes)
540
+
541
+ Graph analysis metrics (density, orphans, clusters) are less meaningful at small scale. Note: "Vault is early-stage. Graph health metrics will become more meaningful as the knowledge graph grows. Focus on capture and processing rather than structural optimization."
542
+
543
+ ### No Research Results
544
+
545
+ If MCP tools fail and bundled reference files are the only source:
546
+ - Read all relevant reference files directly
547
+ - Note in report: "Research grounding from bundled references only. Semantic search unavailable."
548
+ - Recommendations are still valid — reference files contain the core research
549
+
550
+ ### Focus Area Requested
551
+
552
+ If $ARGUMENTS names a specific area:
553
+ 1. Run all phases but weight findings toward the focus area
554
+ 2. Still report other FAIL-level health issues even if outside focus
555
+ 3. Note: "Focused on [area]. Other findings noted but not prioritized."
556
+
557
+ ---
558
+
559
+ ## Quality Standards
560
+
561
+ - Ground every recommendation in specific evidence (health data + friction patterns + research claims) — no intuition-only recommendations
562
+ - Use domain vocabulary throughout — never expose universal terms to a domain user
563
+ - Be opinionated — the research has positions, share them — but explain your reasoning
564
+ - Acknowledge when evidence is thin: "This is speculative based on limited friction data" is honest
565
+ - Distinguish between urgent fixes (FAIL items) and strategic improvements (optimization opportunities)
566
+ - Never recommend more infrastructure than the system's maturity warrants — check the current automation level
567
+ - Every time estimate should be honest — underestimating erodes trust more than overestimating
568
+ - The 25% budget rule is a guideline, not a straitjacket — FAIL-level issues justify exceeding it
@@ -0,0 +1,17 @@
1
+ {
2
+ "name": "knowledge-architect",
3
+ "description": "Research-backed evolution advice for your knowledge system. Analyzes health reports, friction patterns, and derivation history to propose specific changes with research justification.",
4
+ "version": "0.4.0",
5
+ "author": "arscontexta",
6
+ "tags": ["knowledge-management", "meta-cognitive", "maintenance"],
7
+ "entry": "SKILL.md",
8
+ "platform_hints": {
9
+ "claude-code": {
10
+ "context": "fork",
11
+ "model": "opus"
12
+ },
13
+ "openclaw": {
14
+ "type": "external"
15
+ }
16
+ }
17
+ }