Audit — Bitrix Smells

When to use

• The user wants to find agent pile-up (too many or drifting Bitrix agents), component god-objects with business logic in component.php or templates, or leaky module boundaries. Раздувание агентов, god-компоненты и нарушение границ модулей в Битрикс.
• The user wants an audit of an existing 1C-Bitrix project — find legacy/D7 mixing, cache misuse, component god-objects, agent pile-up, or module-boundary smells. Пользователь просит провести аудит Битрикс-проекта и найти проблемы.
• The user wants to find where a Bitrix codebase mixes legacy C*/$APPLICATION globals with the D7 API, or where caching is misused (no cache, wrong keys, stale tags). Смешение legacy и D7, неправильное кеширование в Битрикс.

When NOT to use

• Do not use this skill on a non-Bitrix PHP app (Laravel, Symfony, plain PHP); its checks target Bitrix-specific concepts — the D7 kernel, agents, components, managed cache — that do not exist elsewhere.
• Do not run this audit when the user asks to fix one specific Bitrix bug or implement one component change; make the minimal, legacy-safe edit instead of scanning the whole project.

Core guidance

• Emit structured FINDINGS, not prose — Report each Bitrix smell as a FINDING with id (AUD-BITRIX-{nnn}), title, evidence (path:line), domain, severity, impact, effort (1-5), confidence (0.5-1.0), roi_score, remediation, and tags — never a free-form paragraph.
• Never emit a finding without evidence — Every finding MUST carry concrete evidence as path:line — a component.php line, an agent registration, a cache call, or a cross-module reference you actually read; no location, no finding.
• Remediation for legacy code stays legacy-safe — When a finding sits in working legacy code, the remediation must be legacy-safe — a scoped, reversible, separately signed-off D7 migration — never an opportunistic rewrite folded into an unrelated change. Size effort honestly so big migrations do not masquerade as quick wins.
• Rank findings by ROI score — Compute roi_score = (impact * severity * confidence) / effort for every finding and sort the report descending, so cheap high-impact fixes (agent-to-cron, add cache) rise above expensive legacy migrations.

Decision Engine

Walk this section before choosing an implementation path.

Does the smell sit in working legacy code you must not rewrite, degrade runtime
reliability or performance (agents, cache), or leak a module boundary / concentrate logic
in a god-object?

├── Leaky module boundary or god-object: → Maintainability — business logic packed into component.php or templates, or a module
reaching into another module's internals instead of its public API. Emit a finding;
remediation is extract logic into classes/services and call across modules only via their API.

├── Working legacy code path: → Report the legacy/D7 mixing as a finding, but the remediation must be legacy-safe — propose
a scoped, reversible D7 migration as a separate task, never an opportunistic rewrite during
an unrelated change. Keep effort honest; big migrations rank lower.

└── Degrades runtime reliability or performance: → High impact — agent pile-up, hit-based agents drifting under low traffic, or cache misuse
(no cache on hot data, wrong keys, missing tag invalidation). Emit a finding; remediation is
move time-critical agents to cron and fix the managed-cache keys and tags.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Emit Report

Progress:
- [ ] Build one finding per confirmed smell with `id` (`AUD-BITRIX-{nnn}`), `title`, `evidence`,
`domain`, `severity`, `impact`, `effort`, `confidence`, `remediation`, and `tags`; mark legacy
findings with legacy-safe remediation
- [ ] Compute `roi_score = (impact * severity * confidence) / effort` for each finding and sort the
report descending so cheap high-impact fixes (agent-to-cron, add cache) lead over expensive
legacy migrations
- [ ] For each finding, write remediation that names the fix and links to the Bitrix implementation
skill that performs it (kernel-main-module for D7 and agents, cache-layers for managed cache),
then hand the ranked report off as input to scoped, legacy-safe fix tasks

1. Build one finding per confirmed smell with id (AUD-BITRIX-{nnn}), title, evidence, domain, severity, impact, effort, confidence, remediation, and tags; mark legacy findings with legacy-safe remediation.
   • Verify: Every finding has all required fields populated and a path:line in evidence.
2. Compute roi_score = (impact * severity * confidence) / effort for each finding and sort the report descending so cheap high-impact fixes (agent-to-cron, add cache) lead over expensive legacy migrations.
   • Verify: The report is ordered by roi_score descending with the score shown on each finding.
3. For each finding, write remediation that names the fix and links to the Bitrix implementation skill that performs it (kernel-main-module for D7 and agents, cache-layers for managed cache), then hand the ranked report off as input to scoped, legacy-safe fix tasks.
   • Verify: Each remediation names a next step; legacy items reference the safe-edits strategy and the kernel skill.

Workflow: Scan Bitrix

Progress:
- [ ] Grep for legacy markers (`CModule::IncludeModule`, `$APPLICATION`, `CIBlock`) beside D7
(`\Bitrix\Main`, `Loader`), inspect large component.php/template files, list the agents table,
and find cache calls and cross-module references
- [ ] Open each candidate and confirm the smell — read component.php, check whether an agent runs
from cron or page hits, verify the cache key covers its inputs and has tags, and trace the
cross-module reference — recording the exact path:line
- [ ] Walk the Decision Engine to classify each confirmed smell as legacy-safe, reliability, or
boundary, set severity and impact from that class, estimate effort honestly (legacy migrations
are expensive), and assign confidence

1. Grep for legacy markers (CModule::IncludeModule, $APPLICATION, CIBlock) beside D7 (\Bitrix\Main, Loader), inspect large component.php/template files, list the agents table, and find cache calls and cross-module references.
   • Verify: You have candidate locations for legacy/D7 mixing, cache misuse, component god-objects, agents, and boundary leaks.
2. Open each candidate and confirm the smell — read component.php, check whether an agent runs from cron or page hits, verify the cache key covers its inputs and has tags, and trace the cross-module reference — recording the exact path:line.
   • Verify: Every retained candidate has a confirmed path:line and, for agents, its hit-vs-cron status.
3. Walk the Decision Engine to classify each confirmed smell as legacy-safe, reliability, or boundary, set severity and impact from that class, estimate effort honestly (legacy migrations are expensive), and assign confidence.
   • Verify: Each candidate has severity, impact, effort (1-5) and confidence (0.5-1.0) grounded in its evidence.

Best practices

• In each finding's remediation, point to the implementation skill that performs the fix — the kernel-main-module skill for D7 migration and agents, the cache-layers skill for managed cache and tags — so the reader knows exactly how to act
• Open and read the actual component.php, agent registrations, and cache calls — do not infer smells from directory layout or component names

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Calling cached code correct without checking the key — The presence of cache code does not mean the key and invalidation are correct; those are where cache bugs hide. Fix: Verify the cache key covers every input the result depends on and that tags are registered so content edits invalidate it; raise a finding when either is wrong.
2. Missing that a hit-based agent drifts — Agents without cron are scheduled by page hits, not wall-clock time, so the registered interval is a ceiling, not a guarantee. Fix: Check whether the agent runs from cron (BX_CRONTAB); if a time-critical agent is hit-based, raise a reliability finding recommending the move to OS cron.
3. Flagging all legacy API as a defect — Legacy API is often the only option on old Bitrix cores, and working legacy code carries low risk until it must change. Fix: Score legacy/D7 mixing by inconsistency and churn, keep severity modest for stable isolated legacy, and only raise it where the mix actively causes bugs or blocks a needed change.
4. Hot iblock reads left uncached — Uncached hot reads dominate page time and DB load on Bitrix sites, so they are usually the largest performance win the audit can surface. Fix: Wrap the hot read in managed cache keyed over all varying inputs with tag invalidation, and size the finding's impact by request volume (see bitrix/cache-layers).

Performance notes

• Hot iblock reads left uncached — Missing the highest-impact cache smell — a hot iblock or ORM read (homepage, catalog, menu) executed on every request with no managed cache — because it is spread across templates rather than in one obvious place.

Production checklist

• Agent findings distinguish hit-based from cron-based agents and recommend cron for any time-critical job.
• Every finding carries concrete path:line evidence pointing at code, an agent, or a cache call that was actually read.
• Findings in working legacy code remediate with a scoped, reversible migration proposed as a separate task, never an opportunistic rewrite.
• The pass produces findings and remediation guidance only; it does not edit components, agents, or module code as a side effect.
• Each finding's remediation names a concrete next step and, where one exists, the Bitrix implementation skill that performs it.
• The report lists findings sorted descending by roi_score with impact, severity, effort, and confidence shown.

Version notes

• D7 API availability varies by core age — The namespaced D7 kernel (\Bitrix\Main\Application, Loader, EventManager) is the recommended API from the D7 platform (main ~14+), and BX_CRONTAB-based agent execution is available across supported cores. On very old cores the D7 equivalents may be absent, so legacy calls remain the only option and a migration finding is not always actionable.

Security

• Flag unvalidated request input in components and agents — While scanning component god-objects and legacy code, watch for raw superglobals ($_GET, $_REQUEST) or unchecked kernel Request values fed straight into ORM filters, CIBlockElement::GetList, filesystem paths, or SQL. Raise these as security findings — not just maintainability — citing the file:line, and recommend validating and casting at the boundary.

Testing

• Activation and decision behavior are verified in eval/scenarios/audit/bitrix.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: audit/project-analysis, bitrix/cache-layers, bitrix/kernel-main-module
Behavior constraints: ai-rules/strategy-legacy-safe-edits

Skill contract

Produces: audit.bitrix-findings
Requires: repo.bitrix-project
Risk: medium · Confidence: 0.9