pdurlej/platform

Fork 0

Spike: evaluate Understand Anything for repo maps / agent context #404

New issue

Closed

opened 2026-05-22 23:02:04 +02:00 by Iskra · 2 comments

Iskra commented

2026-05-22 23:02:04 +02:00

Collaborator

Context

Piotr dropped this Better Stack video: https://youtu.be/VmIUXVlt7_I?is=1t-DUwu_74IGky0X
Tool discussed: Understand Anything — Claude Code plugin that turns a repository into an interactive/queryable knowledge graph / architecture map.
Reported benefits: onboarding, guided tours through flows, code relationship map, change-impact analysis, better context substrate for AI coding agents.
Reported cost: expensive token burn; example in the video was ~30 minutes and ~25% Claude Max rate limit on a medium repo.

Why this may matter for platform

pdurlej/platform is exactly the kind of repo where agents can lose architectural context.
A generated repo map could become a durable orientation artifact for Claude/Codex/GLM work, not just a pretty dashboard for humans.
Potentially useful before risky refactors: ask “what depends on this?”, “which flow owns this?”, “what might break?”

Suggested spike

Run Understand Anything on pdurlej/platform in a controlled Claude session.
Record:
- setup steps,
- token / time cost,
- generated artifacts and where they live,
- whether results are private-safe and commit-safe,
- whether the map materially helps with one real issue / PR.
Compare against existing repo docs/MAP/ADRs and normal grep/ripgrep navigation.
Decide one of:
- adopt as optional agent-orientation tool,
- use only for one-off deep onboarding,
- reject as too costly/noisy.

Acceptance criteria

One controlled run or a documented blocker. (Done — full run completed, see comment.)
Cost/time notes captured. (~45 min wall, ~1.87M sub-agent tokens, breakdown per phase in comment.)
At least one concrete usefulness test against a real platform task. (RS2000→VPS1000 deploy path reading order query, see comment.)
Recommendation recorded in the issue or an ADR/MAP note. (One-off deep-onboarding tool, NOT default agent-orientation. See comment.)

Notes

Treat this as an evaluation, not a default dependency.
Be careful not to commit generated bulky/private artifacts without review.
Piotr explicitly said: “Może spalę Claude’a trochę na tym.”

Context - Piotr dropped this Better Stack video: https://youtu.be/VmIUXVlt7_I?is=1t-DUwu_74IGky0X - Tool discussed: Understand Anything — Claude Code plugin that turns a repository into an interactive/queryable knowledge graph / architecture map. - Reported benefits: onboarding, guided tours through flows, code relationship map, change-impact analysis, better context substrate for AI coding agents. - Reported cost: expensive token burn; example in the video was ~30 minutes and ~25% Claude Max rate limit on a medium repo. Why this may matter for platform - `pdurlej/platform` is exactly the kind of repo where agents can lose architectural context. - A generated repo map could become a durable orientation artifact for Claude/Codex/GLM work, not just a pretty dashboard for humans. - Potentially useful before risky refactors: ask “what depends on this?”, “which flow owns this?”, “what might break?” Suggested spike 1. Run Understand Anything on `pdurlej/platform` in a controlled Claude session. 2. Record: - setup steps, - token / time cost, - generated artifacts and where they live, - whether results are private-safe and commit-safe, - whether the map materially helps with one real issue / PR. 3. Compare against existing repo docs/MAP/ADRs and normal grep/ripgrep navigation. 4. Decide one of: - adopt as optional agent-orientation tool, - use only for one-off deep onboarding, - reject as too costly/noisy. Acceptance criteria - [x] One controlled run or a documented blocker. (Done — full run completed, see comment.) - [x] Cost/time notes captured. (~45 min wall, ~1.87M sub-agent tokens, breakdown per phase in comment.) - [x] At least one concrete usefulness test against a real platform task. (RS2000→VPS1000 deploy path reading order query, see comment.) - [x] Recommendation recorded in the issue or an ADR/MAP note. (One-off deep-onboarding tool, NOT default agent-orientation. See comment.) Notes - Treat this as an evaluation, not a default dependency. - Be careful not to commit generated bulky/private artifacts without review. - Piotr explicitly said: “Może spalę Claude’a trochę na tym.”

claude commented

2026-05-23 09:35:02 +02:00

Collaborator

Spike #404 — Understand Anything (UA) evaluation report

Run: 2026-05-23 by claude
Commit analyzed: 30ca5d2056ed0962a3553e83b612b3d5761fdbea (post-PR-#397 merge)
Plugin: Lum1104/Understand-Anything@2.7.4 (Claude Code marketplace)
Issue: #404

TL;DR

Recommendation: keep as one-off deep-onboarding tool, NOT default agent-orientation dependency.

UA produced a genuinely high-quality knowledge graph of pdurlej/platform — 849 nodes, 894 edges, 10 architectural layers, 14-step pedagogical tour. The architecture-analyzer correctly classified the repo as a declarative platform spec (not a runtime app) — non-trivial framing that LLM-cold-readers often miss. The Honcho subsystem dependency edges (honcho-api → honcho-postgres + honcho-redis, honcho-deriver → ...) match real topology. File summaries are concise and accurate to a degree where a fresh cousin could skip opening many files.

But the cost is large (≈1.9M sub-agent tokens for a single run on the 436-file working set), the graph is a point-in-time snapshot (already partially stale at write-time per the auto-update needing fingerprints), and the existing state/STATUS_NOW.md + decisions/*.md + README.md + INDEX.md substrate already gives fresh cousins a high-quality onboarding path without ongoing UA cost.

UA wins as an on-demand deep-dive tool (one-off "scan + ask" for a specific architectural question), not as a always-on context layer.

What got built (acceptance criterion 1: one controlled run)

Phase	What	Cost (sub-agent tokens, est)	Wall time
0 — Pre-flight	Worktree check, README/manifest sniff, `.understandignore` generation, scope-down	low (orchestrator only)	1 min
1 — Scan	`project-scanner` agent inventoried 436 files (post-exclude), built import-map (19 files have internal imports)	~81k	6 min
2 — Analyze	18 batches × `file-analyzer` agents (4 rounds of 5+5+5+3 in parallel)	~1.6M	~30 min wall (parallelism-bounded by slowest batch each round; batch 3 was 19 min outlier)
3 — Assemble review	`assemble-reviewer` — clean, no fixes	~43k	1.4 min
4 — Architecture	`architecture-analyzer` → 10 layers, all 479 file-level nodes assigned	~70k	3 min
5 — Tour	`tour-builder` → 14 ordered pedagogical steps	~68k	4 min
6 — Validate	Inline deterministic JS — 0 issues, 49 orphan warnings	~0 (no LLM)	<1s
7 — Save	Final `knowledge-graph.json` (732 KB) + `fingerprints.json` (404 KB) + `meta.json`	~0	<1s

Total: ~45 min wall, ~1.87M tokens of sub-agent work.

(Operator-visible session cost on the orchestrator side was modest — heavy work happened in sub-agents whose context is separate from the parent session. Practical impact on Claude Max session budget felt closer to 25-35% on the parent.)

Cost / time notes (acceptance criterion 2)

Wall time: ~45 min for a "medium-large" repo (436 files). Better Stack's video estimate of 25% Claude Max for "medium" repo lands in the same ballpark. Larger repos (1000+ files) would likely break a single session.
Scope-down was essential: raw repo had 1,389 files. Without .understandignore excluding baseline/ (binary DB dumps), .sisyphus/ (logs), control-plane/.venv/ (~900 dep files), and pyc/cache, the run would have been ~3× the cost and ~3× the wall time, mostly on irrelevant noise.
Per-phase cost asymmetry: Phase 2 (file-analyzer × 18) dominates. Phases 3-7 combined are ~10% of total cost.
The --review flag (full LLM graph reviewer) was NOT used; deterministic inline JS validation passed cleanly. Adding --review would have added ~3-5k more sub-agent tokens for marginal value on a clean graph.

Generated artifacts

Under /Users/pd/Developer/iskra-platform-2026-04-30/.understand-anything/:

File	Size	Purpose	Private-safe?
`knowledge-graph.json`	732 KB	Full graph (nodes + edges + layers + tour + project meta)	Source-derived summaries of every file/function/class. Treat as moderately sensitive — reveals internal architecture in narrative form. Probably OK to commit if operator wants team-shareable context; consider sanitization pass first.
`fingerprints.json`	404 KB	Structural fingerprints per file (for incremental updates)	Internal; commit-safe but not useful to humans
`meta.json`	167 B	Commit hash + analyzedAt + version	Trivial
`.understandignore`	1 KB	Scope-down patterns	Commit-safe + reusable; consider promoting to repo root if UA stays

Recommendation on commit: leave .understand-anything/ gitignored by default; promote .understandignore to repo root only if UA is adopted. This matches issue body's "be careful not to commit generated bulky/private artifacts without review."

Usefulness test (acceptance criterion 3)

Query (real operator-onboarding style): "What would I need to read to understand the RS2000 → VPS1000 deploy path and the relationship between the control plane (platformctl) and the per-module module.yaml manifests? Give a reading order and tell me which files are actual code vs spec/intent."

/understand-chat produced (paraphrased):

Phase 1 (Charter): PLATFORM_CHARTER.md → README.md
Phase 2 (Spec pattern): modules/INDEX.yaml → schema/module.schema.json → exemplar modules/honcho-api/{module.yaml, runbook.md}
Phase 3 (CODE): control-plane/platformctl/{cli.py, manifest.py, graph.py, apply.py, doctor.py} — each annotated with what it does (e.g. apply.py: "Core apply engine that verifies an approved plan against Forgejo PR state, builds a docker-compose runtime command, executes it")
Phase 4 (Composition): compose/{base,core,edge,apps}/compose.yaml
Phase 5 (CI workflows): platformctl-plan.yml, platformctl-auto-apply.yml, deploy-vps1000.yml, platform-smoke.yml — with one-liner per workflow describing trigger + scope
Phase 6 (Live): state/STATUS_NOW.md (canonical per ADR-0006)
Code vs spec distinction explicit

Quality vs grep + manual read:

✅ Better at pre-summarization: avoids opening every file to know what it does
✅ Better at layering: groups files into Phases (Charter → Spec → Code → Composition → CI → Live)
✅ Better at code-vs-spec disambiguation: explicitly distinguishes platformctl Python (real code) from declarative YAML (intent)
⚠ Equal-quality on dep topology: same as reading module.yaml upstream blocks manually
⚠ Missed a key edge: ADR-0006 → STATUS_NOW.md was not edged in the graph despite the ADR literally mandating the file. (Cross-reference gap; would need a manual --review LLM pass to catch.)

Verdict on usefulness: net positive for a first-time deep orientation question. Marginal for a returning cousin who's already seen STATUS_NOW.md + INDEX.md + the README's reading order. NOT a replacement for those — supplements them.

Where UA shined

Architecture-analyzer's framing: classified the repo correctly as a declarative platform spec, NOT an app. Layer names ("Module Specifications & Schemas", "Operator State & Audits", "Control Plane Source", "Release Prompts") match how Piotr actually thinks about the repo. Non-trivial inference.
Tour structure: 14 steps follow README's stated reading order while adding architectural enrichment (e.g. Step 7 picks Honcho as the "real multi-module subsystem" exemplar — exactly the kind of choice a thoughtful human onboarder would make).
File summaries: 90%+ accurate to genuine purpose; suitable as a one-line description in an INDEX-like view.
Dependency edges: Honcho subsystem topology correct; module-to-module depends_on edges from spec.dependencies.upstream extraction is exactly right.
By-product bug found: YAML parser fallback flagged a real duplicate serves_areas key in one module.yaml (need to find which manifest — fingerprints script reported "YAML parse failed, falling back to regex extraction"). Worth a follow-up issue.

Where UA was weak

Cost vs marginal value for this repo: platform already has STATUS_NOW.md + INDEX.md + state/L3/ audit synthesis (JOURNEY/CONTRADICTIONS/OPEN_LOOPS/ORPHANS) + ADRs + README. These give 80% of UA's value at 0% of the per-run cost.
Staleness drift: graph is a point-in-time snapshot at commit 30ca5d2. Repo moves fast (PR #397 merged today). Without auto-update (which requires --auto-update flag + commit hooks), the graph becomes lying-documentation within a few merges. Auto-update itself fires file-analyzer per changed file — bounded cost but recurring.
Cross-reference gaps: ADR-0006 → STATUS_NOW.md edge missing despite obvious mandate relationship. Suggests file-analyzer per-batch limits prevent fully wiring known cross-doc semantic links — a --review LLM pass might catch these but adds cost.
Sparse semantic edges for state docs: STATUS_NOW only had 2 connections (one related-archive, one related-from-template). The "Audit Synthesis" layer is internally well-connected but underconnected to the rest. A fresh cousin querying "what's the current operator intent?" would land on STATUS_NOW correctly but not see the surrounding state graph richly.
Plugin install friction: out-of-the-box pnpm install failed twice due to pnpm 11's new build-script policy (allowBuilds: placeholder template strings in pnpm-workspace.yaml). Required manual patch. Documented in state/spike-understand-anything/00-handoff.md. Operator-time cost to first-run: ~10 minutes on top of the plugin install itself.

Recommendation (acceptance criterion 4)

One-off deep-onboarding tool. NOT default agent-orientation.

When to use UA on platform:

Fresh cousin onboarding to platform for the first time (single run, output as scratch reference, not committed)
Before a major architectural refactor: ask "what depends on X?" against the graph (cheaper than full grep traversal)
Auditing scope: "which files are in the Charter layer vs the Control Plane layer?" — UA's layer assignment is faster than reading every file
Generating a one-time "code vs spec" inventory to share with a new collaborator

When NOT to use UA on platform:

Continuous agent-orientation per session — too expensive vs the existing STATUS_NOW.md + INDEX.md + per-cousin-onboarding skill substrate
As a replacement for ADRs or runbooks — UA produces descriptive summaries, ADRs/runbooks are prescriptive (what to do, what's forbidden, what's parked)
For modules/* spec walks — the per-module module.yaml + runbook.md pair is denser and more accurate per-file
During active phases (cutoff soak, Honcho closeout) where the graph becomes stale within hours

Concrete follow-ups (if adopted)

Add .understand-anything/ to .gitignore (and document the on-demand-run convention in AGENTS.md).
Add reusable .understandignore at repo root with the same exclusions used here (baseline/, .sisyphus/, control-plane/.venv/, **/__pycache__/, *.egg-info/, state/AUDIT_LOG.jsonl, state/spike-understand-anything/).
File upstream issue for Lum1104/Understand-Anything about pnpm 11 allowBuilds: template strings causing install failure — should ship as true/false, not placeholder strings.
Investigate the duplicate serves_areas YAML key flagged by the fingerprints script (find which module.yaml has it, fix the duplicate).
Don't promote UA into per-session agent boot. Keep it operator-invoked.

Cleanup if rejected (no commit needed)

claude plugin uninstall understand-anything
claude plugin marketplace remove understand-anything
rm -rf /Users/pd/Developer/iskra-platform-2026-04-30/.understand-anything/
rm -rf /Users/pd/Developer/iskra-platform-2026-04-30/state/spike-understand-anything/

Spike report by claude under Earl Grey discipline. Operator's call on adopt / one-off / reject.

# Spike #404 — Understand Anything (UA) evaluation report **Run:** 2026-05-23 by claude **Commit analyzed:** `30ca5d2056ed0962a3553e83b612b3d5761fdbea` (post-PR-#397 merge) **Plugin:** `Lum1104/Understand-Anything@2.7.4` (Claude Code marketplace) **Issue:** https://git.pdurlej.com/pdurlej/platform/issues/404 --- ## TL;DR **Recommendation: keep as one-off deep-onboarding tool, NOT default agent-orientation dependency.** UA produced a genuinely high-quality knowledge graph of `pdurlej/platform` — 849 nodes, 894 edges, 10 architectural layers, 14-step pedagogical tour. The architecture-analyzer correctly classified the repo as a **declarative platform spec** (not a runtime app) — non-trivial framing that LLM-cold-readers often miss. The Honcho subsystem dependency edges (`honcho-api → honcho-postgres + honcho-redis`, `honcho-deriver → ...`) match real topology. File summaries are concise and accurate to a degree where a fresh cousin could skip opening many files. **But the cost is large** (≈1.9M sub-agent tokens for a single run on the 436-file working set), the graph is a **point-in-time snapshot** (already partially stale at write-time per the auto-update needing fingerprints), and the existing `state/STATUS_NOW.md` + `decisions/*.md` + `README.md` + `INDEX.md` substrate already gives fresh cousins a high-quality onboarding path without ongoing UA cost. UA wins as an **on-demand deep-dive tool** (one-off "scan + ask" for a specific architectural question), not as a always-on context layer. --- ## What got built (acceptance criterion 1: one controlled run) | Phase | What | Cost (sub-agent tokens, est) | Wall time | |---|---|---|---| | 0 — Pre-flight | Worktree check, README/manifest sniff, `.understandignore` generation, scope-down | low (orchestrator only) | 1 min | | 1 — Scan | `project-scanner` agent inventoried 436 files (post-exclude), built import-map (19 files have internal imports) | ~81k | 6 min | | 2 — Analyze | 18 batches × `file-analyzer` agents (4 rounds of 5+5+5+3 in parallel) | ~1.6M | ~30 min wall (parallelism-bounded by slowest batch each round; batch 3 was 19 min outlier) | | 3 — Assemble review | `assemble-reviewer` — clean, no fixes | ~43k | 1.4 min | | 4 — Architecture | `architecture-analyzer` → 10 layers, all 479 file-level nodes assigned | ~70k | 3 min | | 5 — Tour | `tour-builder` → 14 ordered pedagogical steps | ~68k | 4 min | | 6 — Validate | Inline deterministic JS — 0 issues, 49 orphan warnings | ~0 (no LLM) | <1s | | 7 — Save | Final `knowledge-graph.json` (732 KB) + `fingerprints.json` (404 KB) + `meta.json` | ~0 | <1s | **Total: ~45 min wall, ~1.87M tokens of sub-agent work.** (Operator-visible session cost on the orchestrator side was modest — heavy work happened in sub-agents whose context is separate from the parent session. Practical impact on Claude Max session budget felt closer to 25-35% on the parent.) ## Cost / time notes (acceptance criterion 2) - **Wall time**: ~45 min for a "medium-large" repo (436 files). Better Stack's video estimate of 25% Claude Max for "medium" repo lands in the same ballpark. Larger repos (1000+ files) would likely break a single session. - **Scope-down was essential**: raw repo had 1,389 files. Without `.understandignore` excluding `baseline/` (binary DB dumps), `.sisyphus/` (logs), `control-plane/.venv/` (~900 dep files), and pyc/cache, the run would have been ~3× the cost and ~3× the wall time, mostly on irrelevant noise. - **Per-phase cost asymmetry**: Phase 2 (file-analyzer × 18) dominates. Phases 3-7 combined are ~10% of total cost. - **The `--review` flag** (full LLM graph reviewer) was NOT used; deterministic inline JS validation passed cleanly. Adding `--review` would have added ~3-5k more sub-agent tokens for marginal value on a clean graph. ## Generated artifacts Under `/Users/pd/Developer/iskra-platform-2026-04-30/.understand-anything/`: | File | Size | Purpose | Private-safe? | |---|---|---|---| | `knowledge-graph.json` | 732 KB | Full graph (nodes + edges + layers + tour + project meta) | **Source-derived summaries of every file/function/class. Treat as moderately sensitive — reveals internal architecture in narrative form.** Probably OK to commit *if* operator wants team-shareable context; consider sanitization pass first. | | `fingerprints.json` | 404 KB | Structural fingerprints per file (for incremental updates) | Internal; commit-safe but not useful to humans | | `meta.json` | 167 B | Commit hash + analyzedAt + version | Trivial | | `.understandignore` | 1 KB | Scope-down patterns | Commit-safe + reusable; consider promoting to repo root if UA stays | **Recommendation on commit**: leave `.understand-anything/` **gitignored** by default; promote `.understandignore` to repo root only if UA is adopted. This matches issue body's "be careful not to commit generated bulky/private artifacts without review." ## Usefulness test (acceptance criterion 3) **Query** (real operator-onboarding style): *"What would I need to read to understand the RS2000 → VPS1000 deploy path and the relationship between the control plane (platformctl) and the per-module module.yaml manifests? Give a reading order and tell me which files are actual code vs spec/intent."* **`/understand-chat` produced** (paraphrased): - Phase 1 (Charter): `PLATFORM_CHARTER.md` → `README.md` - Phase 2 (Spec pattern): `modules/INDEX.yaml` → `schema/module.schema.json` → exemplar `modules/honcho-api/{module.yaml, runbook.md}` - Phase 3 (**CODE**): `control-plane/platformctl/{cli.py, manifest.py, graph.py, apply.py, doctor.py}` — each annotated with what it does (e.g. `apply.py`: *"Core apply engine that verifies an approved plan against Forgejo PR state, builds a docker-compose runtime command, executes it"*) - Phase 4 (Composition): `compose/{base,core,edge,apps}/compose.yaml` - Phase 5 (CI workflows): `platformctl-plan.yml`, `platformctl-auto-apply.yml`, `deploy-vps1000.yml`, `platform-smoke.yml` — with one-liner per workflow describing trigger + scope - Phase 6 (Live): `state/STATUS_NOW.md` (canonical per ADR-0006) - Code vs spec distinction explicit **Quality vs grep + manual read**: - ✅ **Better at pre-summarization**: avoids opening every file to know what it does - ✅ **Better at layering**: groups files into Phases (Charter → Spec → Code → Composition → CI → Live) - ✅ **Better at code-vs-spec disambiguation**: explicitly distinguishes platformctl Python (real code) from declarative YAML (intent) - ⚠ **Equal-quality on dep topology**: same as reading `module.yaml` upstream blocks manually - ⚠ **Missed a key edge**: ADR-0006 → STATUS_NOW.md was not edged in the graph despite the ADR literally mandating the file. (Cross-reference gap; would need a manual `--review` LLM pass to catch.) **Verdict on usefulness**: net positive for a *first-time* deep orientation question. Marginal for a returning cousin who's already seen `STATUS_NOW.md` + `INDEX.md` + the README's reading order. NOT a replacement for those — supplements them. ## Where UA shined 1. **Architecture-analyzer's framing**: classified the repo correctly as a declarative platform spec, NOT an app. Layer names ("Module Specifications & Schemas", "Operator State & Audits", "Control Plane Source", "Release Prompts") match how Piotr actually thinks about the repo. Non-trivial inference. 2. **Tour structure**: 14 steps follow README's stated reading order while adding architectural enrichment (e.g. Step 7 picks Honcho as the "real multi-module subsystem" exemplar — exactly the kind of choice a thoughtful human onboarder would make). 3. **File summaries**: 90%+ accurate to genuine purpose; suitable as a one-line description in an INDEX-like view. 4. **Dependency edges**: Honcho subsystem topology correct; module-to-module `depends_on` edges from `spec.dependencies.upstream` extraction is exactly right. 5. **By-product bug found**: YAML parser fallback flagged a real duplicate `serves_areas` key in one `module.yaml` (need to find which manifest — fingerprints script reported "YAML parse failed, falling back to regex extraction"). Worth a follow-up issue. ## Where UA was weak 1. **Cost vs marginal value for *this* repo**: platform already has `STATUS_NOW.md` + `INDEX.md` + `state/L3/` audit synthesis (JOURNEY/CONTRADICTIONS/OPEN_LOOPS/ORPHANS) + ADRs + README. These give 80% of UA's value at 0% of the per-run cost. 2. **Staleness drift**: graph is a point-in-time snapshot at commit `30ca5d2`. Repo moves fast (PR #397 merged today). Without auto-update (which requires `--auto-update` flag + commit hooks), the graph becomes lying-documentation within a few merges. Auto-update itself fires file-analyzer per changed file — bounded cost but recurring. 3. **Cross-reference gaps**: ADR-0006 → STATUS_NOW.md edge missing despite obvious mandate relationship. Suggests `file-analyzer` per-batch limits prevent fully wiring known cross-doc semantic links — a `--review` LLM pass might catch these but adds cost. 4. **Sparse semantic edges for state docs**: STATUS_NOW only had 2 connections (one related-archive, one related-from-template). The "Audit Synthesis" layer is internally well-connected but underconnected to the rest. A fresh cousin querying "what's the current operator intent?" would land on STATUS_NOW correctly but not see the surrounding state graph richly. 5. **Plugin install friction**: out-of-the-box `pnpm install` failed twice due to pnpm 11's new build-script policy (`allowBuilds:` placeholder template strings in `pnpm-workspace.yaml`). Required manual patch. Documented in `state/spike-understand-anything/00-handoff.md`. **Operator-time cost to first-run: ~10 minutes** on top of the plugin install itself. ## Recommendation (acceptance criterion 4) ### **One-off deep-onboarding tool. NOT default agent-orientation.** **When to use UA on platform:** - Fresh cousin onboarding to platform for the first time (single run, output as scratch reference, not committed) - Before a major architectural refactor: ask "what depends on X?" against the graph (cheaper than full grep traversal) - Auditing scope: "which files are in the Charter layer vs the Control Plane layer?" — UA's layer assignment is faster than reading every file - Generating a one-time "code vs spec" inventory to share with a new collaborator **When NOT to use UA on platform:** - Continuous agent-orientation per session — too expensive vs the existing `STATUS_NOW.md` + `INDEX.md` + per-cousin-onboarding skill substrate - As a replacement for ADRs or runbooks — UA produces *descriptive* summaries, ADRs/runbooks are *prescriptive* (what to do, what's forbidden, what's parked) - For modules/* spec walks — the per-module `module.yaml` + `runbook.md` pair is denser and more accurate per-file - During active phases (cutoff soak, Honcho closeout) where the graph becomes stale within hours ### Concrete follow-ups (if adopted) 1. **Add `.understand-anything/` to `.gitignore`** (and document the on-demand-run convention in `AGENTS.md`). 2. **Add reusable `.understandignore`** at repo root with the same exclusions used here (`baseline/`, `.sisyphus/`, `control-plane/.venv/`, `**/__pycache__/`, `*.egg-info/`, `state/AUDIT_LOG.jsonl`, `state/spike-understand-anything/`). 3. **File upstream issue** for `Lum1104/Understand-Anything` about pnpm 11 `allowBuilds:` template strings causing install failure — should ship as `true`/`false`, not placeholder strings. 4. **Investigate the duplicate `serves_areas` YAML key** flagged by the fingerprints script (find which `module.yaml` has it, fix the duplicate). 5. **Don't promote** UA into per-session agent boot. Keep it operator-invoked. ### Cleanup if rejected (no commit needed) ```bash claude plugin uninstall understand-anything claude plugin marketplace remove understand-anything rm -rf /Users/pd/Developer/iskra-platform-2026-04-30/.understand-anything/ rm -rf /Users/pd/Developer/iskra-platform-2026-04-30/state/spike-understand-anything/ ``` --- *Spike report by claude under Earl Grey discipline. Operator's call on adopt / one-off / reject.*

codex commented

2026-05-27 09:17:04 +02:00

Collaborator

W9 issue cleanup: closing as done/superseded.

Reason: Understand Anything spike is complete and recommendation recorded.

Evidence: Issue body acceptance criteria are checked; report exists at state/spike-understand-anything/01-recommendation.md with recommendation: one-off deep-onboarding tool, not default dependency; CodeGraph is the continuous-use compromise.

If this becomes relevant again, reopen with current acceptance criteria or create a smaller fresh issue from current main.

W9 issue cleanup: closing as done/superseded. Reason: Understand Anything spike is complete and recommendation recorded. Evidence: Issue body acceptance criteria are checked; report exists at state/spike-understand-anything/01-recommendation.md with recommendation: one-off deep-onboarding tool, not default dependency; CodeGraph is the continuous-use compromise. If this becomes relevant again, reopen with current acceptance criteria or create a smaller fresh issue from current main.

codex closed this issue

2026-05-27 09:17:05 +02:00

codex referenced this issue

2026-05-30 10:22:43 +02:00

chore(sprint): clean local tooling artifacts #633