arcadia-1 analog-wiki
Narrative-first knowledge graph for analog circuit design. Stores topologies, sizing strategies, corner lessons, anti-patterns, and project cases. Supports querying, adding entries, tracking relationships, and archiving full project cases with design narratives.
Polanyi Principle
Project narratives are the primary knowledge unit. Rules emerge from cases, not the other way around. Topologies, strategies, corner-lessons, and anti-patterns are indexes into narratives -- they exist because someone learned them in a real project.
Every domain knowledge entry has a derived_from field linking back to the
project(s) where it was learned. A rule without provenance is less trustworthy.
The narrative.md in each project case is the most valuable artifact -- a
free-form design story capturing tacit knowledge that structured YAML cannot.
See shared-references/wiki-schema.md for the full entry and edge schemas.
Effort Gating
Read effort level per shared-references/effort-contract.md. Print at startup:
[effort: <level>] wiki=<mode>
| Effort | Wiki behavior |
|---|---|
| lite | No writes -- read-only queries only |
| standard | lesson_learned only (appended to corner-lessons/) |
| intensive | lesson + sizing strategy entries |
| exhaustive | Full case archive + narrative.md + relationship edges |
Storage
All data lives in the wiki/ directory within the repository.
wiki/
├── index.yml # id -> path + type + one-line summary
├── edges.jsonl # one directed edge per line
├── topologies/ # circuit topology knowledge
├── strategies/ # design/sizing strategies
├── corner-lessons/ # PVT corner surprises
├── anti-patterns/ # known traps
└── projects/ # project cases (gitignored)
└── <project-name>/
├── summary.yml
├── narrative.md
├── trajectory.yml
└── blocks/
└── <block>.yml
wiki/projects/ is gitignored by default (contains private project data).
Users can git add -f specific cases to share them with the team.
Subcommands
/analog-wiki consult <block-type>
Return relevant topologies, strategies, anti-patterns, and historical cases matching the given block type.
python3 tools/wiki_ops.py consult <block-type>
Example:
/analog-wiki consult "folded-cascode"
Returns matching entries across all categories, with derived_from links to project narratives where available.
/analog-wiki add <type>
Interactive creation of a new knowledge entry. Ask the user for name, tags,
and content. Valid types: topology, strategy, corner-lesson, anti-pattern.
python3 tools/wiki_ops.py add <type> --name "..." --tags "..."
The tool assigns the next available ID (e.g., topo-002, strat-004) and
updates wiki/index.yml.
/analog-wiki relate <id1> <rel> <id2>
Add a directed relationship edge between two entries.
python3 tools/wiki_ops.py relate <id1> <rel> <id2>
10 valid relations:
| Relation | Meaning |
|---|---|
contains |
A contains B as a sub-component |
instance_of |
A is a concrete instance of topology B |
extends |
A extends/improves on B |
contradicts |
A's findings contradict B |
prevents |
Applying A prevents anti-pattern B |
discovered_in |
Lesson A was discovered in project B |
validated |
Case A validated strategy B |
invalidated |
Case A invalidated strategy B |
supersedes |
A replaces B (B should be deprecated) |
requires |
A requires B as a prerequisite |
Edges are appended to wiki/edges.jsonl. Dangling edges (target not found)
are silently skipped during queries.
/analog-wiki archive-project
Extract cases from the current project's iteration-log.yml. Creates:
summary.yml-- architecture, final specs, convergence counttrajectory.yml-- parameter change trajectory from iteration log- Placeholder
narrative.md-- prompts the architect to write the design story (the most valuable artifact)
python3 tools/wiki_ops.py archive-project --iteration-log iteration-log.yml
After creating the placeholder, prompt the architect to write the narrative. The narrative captures tacit knowledge: what was tried, what failed, and why.
/analog-wiki deprecate <id>
Mark an entry as deprecated (confidence: deprecated).
python3 tools/wiki_ops.py deprecate <id>
/analog-wiki search <query>
Full-text search across all wiki entries.
python3 tools/wiki_ops.py search <query>
Interaction with Other Skills
| Skill | Interaction |
|---|---|
| analog-decompose | Calls consult at start for architecture references |
| analog-design | Calls consult for sizing strategies and anti-patterns |
| analog-verify | On convergence, suggests pushing a block-case entry |
| analog-pipeline | Triggers archive-project at end (effort >= standard) |
All pushes are advisory ("suggest archiving"), never mandatory. The user can always skip.
Seeding
Initial wiki entries can be created from existing knowledge in:
shared-references/cmfb.md-- CMFB design knowledgeprompts/designer-prompt.md-- sizing methodology and strategies
Use /analog-wiki add to formalize these into structured entries with proper
derived_from provenance.
Standalone Use
This skill can be used independently -- it does not require /analog-pipeline.
Any skill or user can query, add, relate, or archive entries directly.