Audit — Project Analysis

When to use

• The user asks to audit, review, assess, or analyse an existing (brownfield) PHP project and wants prioritised findings rather than a single one-off fix.
• The user wants a whole-project analysis that surfaces the top problems ranked by ROI — an end-to-end brownfield pass, not a single fix (проанализируй проект и дай топ проблем по ROI, проведи аудит и составь топ проблем).
• The user wants a structured findings report with ids, evidence, severity, and a ROI ranking so remediation work can be prioritised across a backlog.
• The user needs to quantify technical debt across a legacy PHP project and decide what to fix first based on impact, effort, and confidence.

When NOT to use

• Do not run a project audit when starting a brand-new project with no existing code to sample; there is nothing to gather evidence from yet.
• Do not open a full audit to fix one already-identified bug; apply the targeted fix with the relevant implementation skill instead of producing a findings report.

Core guidance

• Cross-link remediation to an implementation skill — Point each finding's remediation at the concrete implementation skill that fixes it (for example a php migration, an injection-prevention, or a caching skill), so the audit hands off directly to executable guidance.
• Every finding cites path and line evidence — Never emit a finding without concrete evidence — cite it as path/to/file.php:line (or a path range). A finding with no location is a hypothesis, not a finding.
• Emit findings in the canonical structured schema — Emit each finding with the full schema — id (AUD-{domain}-{nnn}), title, evidence (path:line), domain, severity, impact, effort, confidence, roi_score, remediation, and tags — so findings sort and compose across packs.
• Rank findings by the ROI score — Compute roi_score = (impact * severity * confidence) / effort for every finding and sort the report descending, so the highest-leverage, lowest-cost fixes surface first. Rate impact, severity, and effort on 1-5 and confidence on 0.5-1.0.
• Sample real files before generalising — Ground every finding in files that actually exist in the repo — grep, open, and read representative modules before asserting a systemic problem. Report the sampled paths so the reader can extend the audit.

Decision Engine

Walk this section before choosing an implementation path.

Where are you in the audit — no stack profile yet, findings gathered but unmerged,
merged but unranked, or ranked and ready to deliver?

├── findings gathered but overlapping: → merge phase — dedupe findings that describe the same root cause across domains,
merge their evidence, and keep the highest severity so one issue is not counted twice.

├── merged, ready to rank and deliver: → rank-and-deliver phase — delegate ranking to audit/roi-prioritization and formatting
to audit/findings-report, producing the Top 20 by ROI, quick wins, and strategic
backlog as the final findings-ranked deliverable.

├── no stack profile yet: → recon phase — delegate to audit/stack-detection to produce the stack-detected
profile, then scope each domain scan to the frameworks and version it reports.

└── profile ready, no findings yet: → scan phase — sample real files per domain (security, performance, php version,
framework conventions) and emit each issue as a structured, evidence-backed finding.

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

Workflows

Workflow: Run Audit

Progress:
- [ ] Detect the stack from `composer.json`, `php -v`, and framework markers, then grep
and open representative modules for each domain (php, security, performance)
- [ ] For each issue, write a finding with `id` AUD-{domain}-{nnn}, a `title`, `evidence`
as `path:line`, `domain`, and 1-5 ratings for `severity`, `impact`, and `effort`
plus a 0.5-1.0 `confidence`
- [ ] Compute `roi_score = (impact * severity * confidence) / effort`, sort findings
descending, and set each `remediation` to the implementation skill that fixes it
- [ ] Group findings by root cause across domains and merge duplicates — union the
evidence and tags, keep the highest severity and impact — so each real issue appears
exactly once before ranking
- [ ] Hand the merged findings to audit/roi-prioritization to rank and band them, then to
audit/findings-report to render the Top 20 by ROI, quick wins, and strategic backlog
as the findings-ranked deliverable

1. Detect the stack from composer.json, php -v, and framework markers, then grep and open representative modules for each domain (php, security, performance).
   • Verify: You can name the PHP version, frameworks, and the concrete files you sampled.
2. For each issue, write a finding with id AUD-{domain}-{nnn}, a title, evidence as path:line, domain, and 1-5 ratings for severity, impact, and effort plus a 0.5-1.0 confidence.
   • Verify: Every finding has an id, a path:line evidence string, and all rating fields set.
3. Compute roi_score = (impact * severity * confidence) / effort, sort findings descending, and set each remediation to the implementation skill that fixes it.
   • Verify: The report is sorted by roi_score and each finding links a remediation skill.
4. Group findings by root cause across domains and merge duplicates — union the evidence and tags, keep the highest severity and impact — so each real issue appears exactly once before ranking.
   • Verify: No two findings point at the same root cause and every merged finding keeps its evidence.
5. Hand the merged findings to audit/roi-prioritization to rank and band them, then to audit/findings-report to render the Top 20 by ROI, quick wins, and strategic backlog as the findings-ranked deliverable.
   • Verify: The output is an ROI-ranked report with the three sections and a remediation per row.

Workflow: Navigate Hub

Progress:
- [ ] Check what already exists — a stack profile, raw findings, merged findings, a ranked
list — and use the phase tree to identify which of recon, scan, merge, rank, or
deliver you are actually in
- [ ] Delegate the current phase to its specialist — stack-detection for recon,
roi-prioritization for ranking, findings-report for delivery — then return to the hub
to advance to the next phase

1. Check what already exists — a stack profile, raw findings, merged findings, a ranked list — and use the phase tree to identify which of recon, scan, merge, rank, or deliver you are actually in.
   • Verify: You can name the current phase and the artifact it must produce next.
2. Delegate the current phase to its specialist — stack-detection for recon, roi-prioritization for ranking, findings-report for delivery — then return to the hub to advance to the next phase.
   • Verify: The right specialist skill ran for the phase and control returned to the hub.

Best practices

• Between scanning and ranking, merge findings that describe the same root cause — union their evidence and tags, keep the highest severity and impact — so one issue is ranked once, not several times under different domains
• Treat this skill as the hub — delegate recon to audit/stack-detection, scoring and banding to audit/roi-prioritization, and formatting to audit/findings-report, while keeping the end-to-end order and the finding schema consistent across them

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Leaving effort unset or zero in the ROI formula — A missing denominator silently corrupts the ranking and pushes cheap-looking but expensive fixes to the top. Fix: Always estimate effort on the 1-5 scale (1 = minutes, 5 = a multi-day refactor) before computing the ROI score.
2. Findings asserted without a file location — Reviewers cannot triage or fix what they cannot locate, and unlocated claims hide false positives. Fix: Attach evidence: path/to/File.php:42 to every finding; if you cannot cite a location, downgrade it to a note or drop it.
3. Marking every finding critical — If everything is urgent, nothing is; the team cannot tell the genuine emergency from routine cleanup. Fix: Reserve critical for exploitable or data-loss risks, and calibrate severity 1-5 against a shared rubric so the ROI sort stays meaningful.

Production checklist

• No finding is recorded without a path or path-and-line pointer to real code that a reviewer can open.
• Findings sharing a root cause across domains are deduped into one, so no issue is counted or ranked twice.
• The deliverable presents findings ROI-ranked with a Top 20, quick wins, and strategic backlog, each linking a remediation.
• A stack-detected profile exists and every domain scan is scoped to the frameworks and PHP version it reports.
• Each finding has id, title, evidence, domain, severity, impact, effort, confidence, roi_score, remediation, and tags.
• No credential, key, or personal record is pasted into the report; evidence cites the location but redacts the value.

Version notes

• The audit method spans PHP 7.4 through 8.4 (PHP >=7.4) — The finding schema and ROI ranking are version-agnostic and apply to any PHP 7.4+ codebase; only the domain-specific checks (for example php version drift) tighten their thresholds against the target's PHP version.

Security

• Redact secrets and PII from audit evidence — When quoting evidence, cite the path:line but redact any secret, credential, or personal data found there — never paste an API key, password, or customer record into the findings report.

Testing

• Activation and decision behavior are verified in eval/scenarios/audit/project-analysis.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

Prerequisites: audit/roi-prioritization, audit/stack-detection
Related: audit/bitrix, audit/findings-report, audit/laravel, audit/performance, audit/php, audit/refactoring, audit/roi-prioritization, audit/security, audit/stack-detection, databases/redis, php/migrate-php74-to-php80, security/sql-injection-prevention
Behavior constraints: ai-rules/strategy-no-untested-refactor

Skill contract

Produces: audit.findings-ranked
Requires: audit.stack-detected, repo.php-sources
Risk: low · Confidence: 0.9