Loctree gives sight.
AICX gives insight.
𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. gives hands to craft products.
For structural orientation start with Loctree. (NEW!
>=0.12: Now also for literal occurrences).
This repository should be treated as a structural living system. To help you
to not treat it as a loose pile of files and to boost velocity without
loosing orientation in complexity you are equipped with advanced AST engine
represented by loctree-mcp and loct cli tool.
Before making structural assumptions, inspect the map.
Before changing behavior, understand impact.
Before creating new symbols, check whether the shape already exists.
Loctree is the default structural map at session start and for further repository work. It makes dependencies, blast radius, symbols, runtime entry points, dead surfaces, duplicates, and exact occurrences visible faster than manual rummaging.
- Loctree MCP
- Loct CLI
- Local tools (
rg,grep,awk,sed,cat) - Manual inspection
| Action | Preferred Tool |
|---|---|
| Edit file | slice(file) |
| Delete file | impact(file) |
| Rename file | impact(file) |
| Refactor | impact(file) |
| Create symbol | find(name) |
Use:
find --literalloct occurrences IDENTIFIERloct body SYMBOL
before broad text search.
Use:
rggrepawksedcat
when Loctree cannot answer cleanly.
For external users and downstream adopters, loctree-fail.md is the intake
channel for bugs, missing language coverage, UX problems, and fallback cases.
They append enough evidence for the Loctree team to reproduce and prioritize.
For Loctree contributors working inside this repository, an observed or reported Loctree failure is product work, not note-taking. The order is:
- Reproduce the failure.
- Add a focused test or contract.
- Fix it in the same cut when the scope is bounded.
- Append to
loctree-fail.mdonly when repair cannot land now, and state the concrete blocker.
If Loctree is:
- wrong (blind, false positive, misleading)
- stale (even after manual force rescan)
- slow (for 200k LOC repositories)
- awkward (proper but noisy or mishaped)
- missing language support (despite claiming support)
- missing an important surface (feature request)
- suggesting an obvious improvement (nitpicks)
check the --version you currently use and append a note to:
.loctree/loctree-fail.md
Be aware that version check is crucial, as ome functions like
find --literalare available inv0.12.xor upper.
- Never recreate the file.
- Never overwrite the file.
- Always append.
- bugs
- missing features
- UX problems
- performance issues
- language coverage issues
- fallback situations
Do not ommit the entry because you sweeped the file and already found a similar case descriptions. Repeated reports are signal, not noise.
Loctree changes agent work from:
text rummaging
into:
map-first engineering
The goal is not obedience.
The goal is:
- fewer wrong edits
- better blast-radius judgement
- faster recovery
- more honest runtime decisions
Start with vc-init. Do not assume repository shape from filenames alone.
Always identify:
- subsystem
- entry points
- symbols
- ownership boundaries
- likely blast radius
Prefer structural inspection over broad search whenever the question is about:
- dependency
- ownership
- impact
- location
You can use raw text search even when:
- the question is literal
- the question is local
You gain beautiufly curated context around your search. If loctree-mcp or
loct cli fail, report it honestly and fall back into rg, grep, awk,
sed or any tool you are familiar with.
Before modifying code:
- Locate the target.
- Inspect local implementation.
- Inspect callers and dependents.
- Check nearby tests, examples, and docs.
- Make the smallest coherent change.
- Verify through the closest runtime path.
If verification cannot be run:
Say so explicitly.
Before introducing:
- abstractions
- helpers
- parsers
- services
- commands
- components
- config paths
check whether one already exists.
If you introduce a new path:
Explain why reuse was incorrect.
Avoid duplicate systems created only because the agent did not look hard enough.
Static structure matters.
Runtime behavior decides.
When changing:
- execution
- configuration
- packaging
- CLI behavior
- API contracts
- generated artifacts
verify against the real execution path whenever possible.
Passing type checks is useful.
It is not the same thing as product readiness.
Prefer changes that improve understanding.
Avoid cleverness that hides shape.
Preserve naming consistency.
Do not bury important behavior inside glue code.
If a file becomes a dumping ground:
Call it out.
Do not:
- revert
- delete
- rewrite
code you do not understand.
Do not assume unfamiliar changes are safe to discard.
If the repository is moving:
Re-read before acting.
Treat concurrent agents or human work as part of the system.
Always state:
- what changed
- why it changed
- what was verified
- what was not verified
- what remains risky
- what should be checked next
Do not hide uncertainty.
Do not claim confidence you have not earned.
Every AICX problem observed while working in this repository must be appended to the operator-managed log:
~/.aicx/aicx-problems.md
Problem means: bug, regression risk, flaky behavior, contract drift, docs/runtime mismatch, tooling failure, test gap, zombie path, unsafe fallback, or a working decision likely to return as product debt.
Rules:
- Append at the end. Never overwrite or reorganize the log.
- Do not skip an entry because a similar one may already exist. Repetition is signal.
- Do not store secrets, tokens, PII, PHI, full private payloads, or private customer/session material. Redact and describe the shape instead.
- Keep Loctree tool failures in
.loctree/loctree-fail.md; keep AICX product and runtime problems in the AICX problem log above. - Preferred helper:
tools/aicx_problem_log.sh "short title" <<'EOF' ... EOF - If the helper fails, append manually. Missing helper is not a reason to skip the log.
Loctree gives sight.
AICX gives insight.
𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. gives hands to craft products.
For structural orientation start with Loctree. (NEW!
>=0.12: Now also for literal occurrences).
This repository should be treated as a structural living system. To help you
to not treat it as a loose pile of files and to boost velocity without
loosing orientation in complexity you are equipped with advanced AST engine
represented by loctree-mcp and loct cli tool.
Before making structural assumptions, inspect the map.
Before changing behavior, understand impact.
Before creating new symbols, check whether the shape already exists.
Loctree is the default structural map at session start and for further repository work. It makes dependencies, blast radius, symbols, runtime entry points, dead surfaces, duplicates, and exact occurrences visible faster than manual rummaging.
- Loctree MCP
- Loct CLI
- Local tools (
rg,grep,awk,sed,cat) - Manual inspection
| Action | Preferred Tool |
|---|---|
| Edit file | slice(file) |
| Delete file | impact(file) |
| Rename file | impact(file) |
| Refactor | impact(file) |
| Create symbol | find(name) |
Use:
find --literalloct occurrences IDENTIFIERloct body SYMBOL
before broad text search.
Use:
rggrepawksedcat
when Loctree cannot answer cleanly.
For external users and downstream adopters, loctree-fail.md is the intake
channel for bugs, missing language coverage, UX problems, and fallback cases.
They append enough evidence for the Loctree team to reproduce and prioritize.
For Loctree contributors working inside this repository, an observed or reported Loctree failure is product work, not note-taking. The order is:
- Reproduce the failure.
- Add a focused test or contract.
- Fix it in the same cut when the scope is bounded.
- Append to
loctree-fail.mdonly when repair cannot land now, and state the concrete blocker.
If Loctree is:
- wrong (blind, false positive, misleading)
- stale (even after manual force rescan)
- slow (for 200k LOC repositories)
- awkward (proper but noisy or mishaped)
- missing language support (despite claiming support)
- missing an important surface (feature request)
- suggesting an obvious improvement (nitpicks)
check the --version you currently use and append a note to:
.loctree/loctree-fail.md
Be aware that version check is crucial, as ome functions like
find --literalare available inv0.12.xor upper.
- Never recreate the file.
- Never overwrite the file.
- Always append.
- bugs
- missing features
- UX problems
- performance issues
- language coverage issues
- fallback situations
Do not ommit the entry because you sweeped the file and already found a similar case descriptions. Repeated reports are signal, not noise.
Loctree changes agent work from:
text rummaging
into:
map-first engineering
The goal is not obedience.
The goal is:
- fewer wrong edits
- better blast-radius judgement
- faster recovery
- more honest runtime decisions
Start with vc-init. Do not assume repository shape from filenames alone.
Always identify:
- subsystem
- entry points
- symbols
- ownership boundaries
- likely blast radius
Prefer structural inspection over broad search whenever the question is about:
- dependency
- ownership
- impact
- location
You can use raw text search even when:
- the question is literal
- the question is local
You gain beautiufly curated context around your search. If loctree-mcp or
loct cli fail, report it honestly and fall back into rg, grep, awk,
sed or any tool you are familiar with.
Before modifying code:
- Locate the target.
- Inspect local implementation.
- Inspect callers and dependents.
- Check nearby tests, examples, and docs.
- Make the smallest coherent change.
- Verify through the closest runtime path.
If verification cannot be run:
Say so explicitly.
Before introducing:
- abstractions
- helpers
- parsers
- services
- commands
- components
- config paths
check whether one already exists.
If you introduce a new path:
Explain why reuse was incorrect.
Avoid duplicate systems created only because the agent did not look hard enough.
Static structure matters.
Runtime behavior decides.
When changing:
- execution
- configuration
- packaging
- CLI behavior
- API contracts
- generated artifacts
verify against the real execution path whenever possible.
Passing type checks is useful.
It is not the same thing as product readiness.
Prefer changes that improve understanding.
Avoid cleverness that hides shape.
Preserve naming consistency.
Do not bury important behavior inside glue code.
If a file becomes a dumping ground:
Call it out.
Do not:
- revert
- delete
- rewrite
code you do not understand.
Do not assume unfamiliar changes are safe to discard.
If the repository is moving:
Re-read before acting.
Treat concurrent agents or human work as part of the system.
Always state:
- what changed
- why it changed
- what was verified
- what was not verified
- what remains risky
- what should be checked next
Do not hide uncertainty.
Do not claim confidence you have not earned.