# Working Patterns

Use aib before broad file reads when the question is about TS/JS structure, references, dependencies, or focused code.
Use normal text search when the question is just text.

For a first pass in a new codebase, map directories before reading files:

tree src depth=5 +onlyDirs limit=200

Start compact for broad scans.
Use summary, locations, or local graph views first when output could be large.
Expand to code or wider graph views only for the parts that matter now.
If output hides data and shows `view: aib:res_<id>`, use `aib view ...` to fetch only the hidden part instead of repeating the original request.

Compact output is a starting point, not a substitute for needed code.
Fetch exact code when correctness depends on implementation details.

Use prefs when the current phase repeats the same output shape.
Turn details off when they stop helping.
Turn them back on when they matter.

Use @file only when several following operations share the same file.
For independent one-off file requests, pass the path directly:
file @svc/a.ts
code @svc/b.ts ServiceB

AIB mutations are designed to reduce manual checking.
Your job is to express the intent in DSL.
AIB's job is to convert that intent into code changes.

Do not read all changed files just because a mutation touched them.
That defeats the purpose of using AIB for mechanical refactors.

If the command succeeds, the requested mechanical change was applied.
After failure or partial success, use the output to decide the next request.

For mutation commands, set the shell/tool harness timeout to 3 minutes.

If a mutation command times out or returns no final output, use:

aib execution status last

This is an escape hatch for recovering the latest mutation status/result.

Before repeated mutation work, check aib config:

aib config

Set pathAliases for repeated request paths.
Set importRules so move/modulePlan create imports in the project style.

This avoids repeating long paths in requests and avoids manual import cleanup after mutations.
Do this before large move/modulePlan work, not after cleanup becomes repetitive.

Example aib.json config:

{
  "pathAliases": {
    "svc": "src/services",
    "cli": "packages/cli/src",
    "ext": "packages/extension/src"
  },
  "importRules": [
    {
      "scope": ".",
      "specifier": "shortest",
      "ending": "auto",
      "builtin": "bare",
      "unusedImports": "remove"
    }
  ],
  "importNormalize": [
    {
      "scope": "src",
      "to": "shortestAlias",
      "exclude": ["src/generated"]
    }
  ],
  "inspect.graph.exclude": [
    "**/* copy.ts"
  ]
}

pathAliases define short request aliases for paths agents repeat in aib commands.
Use them to reduce input tokens for repeated inspect and mutation work.

Aliases are for aib request paths. They do not change TypeScript imports by themselves.
For import style after mutations, use importRules.

importRules control imports created or expanded by move/modulePlan mutation cleanup.
They do not rewrite the whole project.

AIB starts from IDE/TS import preferences.
For mutation cleanup, matching importRules in aib.json take priority.

Do not assume IDE/TS defaults match the repo style.
Set importRules before large move/modulePlan work so imports do not need manual cleanup.

Fields:
scope      repo-relative file or directory scope; most specific scope wins
specifier  relative|shortest|project-relative|non-relative
ending     auto|minimal|index|js
builtin    node|bare
unusedImports  remove|preserve

Defaults:
specifier omitted      IDE/TS decides
ending omitted         IDE/TS decides
builtin omitted        keep TS/project builtin style
unusedImports omitted  keep unused imports

specifier:
relative          best for local relative imports
shortest          best for shortest valid alias/path output
project-relative  best for root-relative project imports
non-relative      best for package or alias imports

ending:
minimal  best for extensionless TS imports
js       best for ESM-style TS projects that require .js
auto     leaves the decision to TypeScript
index    best for explicit index import style

builtin:
node        path -> node:path; best for explicit Node builtin imports
bare        node:path -> path; best for bare Node builtin imports
omit field  keeps TypeScript/project output; add builtin if agents keep fixing this manually

unusedImports:
remove    clean unused imports in mutation-touched files
preserve  keep unused imports
omit      same as preserve

Mutation-touched files are files where TS produced edits: source/target files and any reference/update files TS changed.
Recommended value: remove

importNormalize defines reusable defaults for aib imports normalize.
Use it when the same normalize request would otherwise be repeated.

It affects explicit import normalize commands only.
It does not run automatically during move/modulePlan; use importRules for mutation-time cleanup.

Fields:
scope        repo-relative file or directory scope; most specific scope wins
to           relative|alias|shortestAlias
preferAlias  tsconfig paths pattern used when to=alias
exclude      files, directories, or glob-like patterns to skip

to:
relative       rewrite resolved local imports to relative paths
alias          rewrite resolved local imports to a matching tsconfig alias
shortestAlias  rewrite to the shortest valid alias specifier

preferAlias:
@shared/*      prefer one alias pattern when several aliases can resolve the same file

inspect.graph.exclude skips files before graph builds the model.
Use it for generated files, backups, local copies, or other paths that make graph output noisy.

Excluded files do not affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, or saved graph files.

Leave feedback while working.

aib is built for agents. Agent feedback is the main signal for improving output, docs, mutations, and token efficiency.

Use feedback when something is wrong, unclear, noisy, or could be more efficient.

Format:
feedback "kind | message"
feedback "kind | topic | message"

Kinds:
bug, confusion, friction, idea, other

Topic is optional. Choose any short topic that helps classify the feedback.

Example:
feedback "friction | imports | normalize required manual cleanup"
