Project Audit (تحقق شامل للمشروع)
Reply in the owner's language (profile; default Egyptian Arabic). The report itself is always written in Arabic.
Goal
Produce one Arabic Markdown file giving the developer:
- An inventory of every real problem (security, code quality, performance, architecture), with no padding and no fabricated issues.
- For each issue: the fix, the reasoning behind it, and a generalizable lesson for future projects.
The report is the deliverable; everything else exists to make it accurate and useful.
Workflow
Four phases, in order; early phases inform later ones.
Phase 1: Reconnaissance (استكشاف المشروع)
Before opening any source file, map what you're auditing.
- List the project tree (exclude
node_modules/, .git/, vendor/, dist/, build/, .next/, target/, __pycache__/, lock files, other generated/vendored content).
- Identify the stack: language(s), framework(s), runtime, database, build system (
package.json, requirements.txt, Gemfile, pom.xml, Cargo.toml, go.mod, etc.).
- Identify the project type: web API, full-stack app, CLI, library, mobile app, infra config, etc. The type decides which threats matter most.
- Find entry points:
main.*, index.*, route definitions, request handlers, CLI parsers, background workers, cron jobs.
- Find configuration and secret-handling code:
.env*, config/, settings files, anything reading process.env / os.environ.
Output (internal, not in the report): a short stack summary and where the critical code lives. It drives where you spend audit time.
Phase 2: Multi-dimensional scan (الفحص متعدد الأبعاد)
Walk the source files systematically. Run each substantive file past all four pillars while it's open; don't audit one pillar at a time across the whole project (wastes context).
Excluded: vendored code, generated code, minified bundles, test fixtures (unless they leak secrets), migrations (unless logic-bearing).
The four pillars are weighted equally. Don't let security findings crowd out architectural ones or vice versa; an unmaintainable module is as worth reporting as a missing validation check.
Phase 3: Cross-file and deep-dive analysis (التعمّق)
After the file-by-file scan, look at the project holistically:
- Patterns: the same mistake in many places is one finding, not twenty. Note the pattern and list affected files.
- Cross-cutting concerns: authentication, error handling, logging, config loading, database access. Audit them as systems, not individual files.
- Missing pieces: what should be there but isn't (tests, input validation layer, rate limiting on a public API, error monitoring). Absence is a finding.
- Dependency hygiene: outdated packages, known CVEs, abandoned deps, suspiciously rare packages (supply-chain risk).
Phase 4: Write the report (كتابة الريبورت)
Compile findings into the exact format below, in Arabic. Save to /mnt/user-data/outputs/audit-report.md (or a descriptive filename if the project has a name) and present it via present_files.
Audit checklists
Prompts to think about each axis, not boxes to tick; don't force a finding under every bullet.
🔒 Security (الأمن)
- Injection: SQL/NoSQL, command, LDAP, template (SSTI), XPath. Look for string concatenation into queries/commands/templates.
- Cross-site (web): XSS (reflected, stored, DOM), CSRF (missing tokens or SameSite), open redirects, clickjacking (missing frame-ancestors / X-Frame-Options).
- Authentication and sessions: weak password storage (no bcrypt/argon2/scrypt, low cost), predictable tokens, no session expiry, JWT misuse (
alg: none, secrets in client, no expiry).
- Authorization: missing access checks, IDOR, privilege escalation paths, broken multi-tenancy isolation.
- Secrets in code: API keys, DB passwords, private keys, tokens hardcoded or committed;
.env* files in the tree; default credentials.
- Cryptography: MD5/SHA1 for security, ECB mode, hardcoded IVs, custom crypto, weak random (
Math.random/rand for tokens).
- Input validation: trusting user input (path traversal, upload type/size checks, deserializing untrusted data: pickle, YAML.load, Java deserialization).
- Output handling: unescaped output in HTML/SQL/shell, content-type sniffing, missing or overly permissive CORS (
* with credentials).
- Dependencies: known-vulnerable versions (check advisories), known supply-chain compromises.
- Insecure defaults: debug mode in production, verbose error pages leaking stack traces, default admin credentials, permissive file permissions.
- Logging and secrets: PII/secrets in logs, full request bodies logged, tokens echoed in errors.
🧹 Code quality (جودة الكود)
- Bugs: off-by-one, null/undefined dereference, async race conditions, bad error handling (swallowed exceptions, catch-all, errors turned into nulls), wrong comparisons (
== vs ===, float equality), resource leaks (unclosed files/connections/streams).
- Error handling: missing at boundaries (network, filesystem, DB);
null meaning "error" undocumented; catch that logs and continues when it shouldn't; inconsistent error shapes.
- Dead code and duplication: unused functions/files/imports, commented-out code, copy-pasted blocks to extract.
- Complexity: functions doing too much, deep nesting, long parameter lists, god-objects. Name the worst offenders.
- Naming and readability: misleading names (a
validate that mutates), obscuring abbreviations, inconsistent conventions.
- Comments and docs: comments contradicting code (strong bug signal; one is wrong), missing docs on public APIs, stale TODOs/FIXMEs.
- Type safety: excessive
any / dynamic / untyped dicts where stronger typing is expected; missing return types on public functions.
- Tests: none on critical paths, tests asserting nothing, brittle tests coupled to implementation, flaky time/network tests, no integration tests for important flows.
⚡ Performance (الأداء)
- Database: N+1 queries, missing indexes on filter/join columns, SELECT * in hot paths, no pagination on potentially large results, transactions held open across slow operations.
- Algorithmic: O(n²) where O(n) is possible, nested loops over the same large data, sorting in inner loops, recomputing the same value.
- I/O and blocking: synchronous I/O in async/event-loop code, blocking the main thread, missing batching (one HTTP request per item instead of bulk).
- Memory: loading whole large files instead of streaming, retained references that should be GC'd, large objects needlessly in module scope.
- Caching: missing on expensive deterministic computation, missing HTTP cache headers, invalidation bugs.
- Frontend (if applicable): large unsplit bundles, unoptimized images, render-blocking resources, re-renders from unstable references, missing memoization where it matters, hydration mismatches.
- Network: chatty APIs (many small calls where one batched call would do), missing compression, missing connection pooling.
🏛️ Architecture (المعمارية)
- Separation of concerns: business logic mixed with framework code, handlers doing data access directly, DB queries in view templates, side effects in pure-looking functions.
- Coupling: modules depending on each other's internals, circular dependencies, hidden coupling via shared mutable state.
- Boundaries: no clear layer boundaries (domain <-> infrastructure), framework types leaking into the domain (ORM models as API responses without DTOs).
- Scalability: in-memory state where horizontal scaling is expected, sticky-session assumptions, shared-filesystem assumptions, no idempotency on side-effectful endpoints.
- Configuration: magic numbers, config scattered across files, no environment separation, secrets and feature flags mixed.
- Dependency direction: high-level modules depending on low-level ones (rather than both on abstractions), domain depending on infrastructure.
- Error/result propagation: exceptions in some places and return values in others without convention; context lost as errors bubble up.
- Observability: critical operations without logs, no structured logging, no correlation IDs across async boundaries, no metrics on key business operations.
Severity classification (تصنيف الخطورة)
Use these five levels and emoji prefixes; the report grouping depends on them.
- 🔴 حرج (Critical): active exploitability, data loss, possible production outage, or a flaw triggerable remotely without authentication. E.g. SQL injection, hardcoded admin password, broken authentication.
- 🟠 عالي (High): real exploitability with prerequisites, or a bug that hits users in production under normal conditions. E.g. IDOR needing an authenticated user, N+1 on a hot endpoint, missing CSRF on a state-changing form.
- 🟡 متوسط (Medium): real but limited impact, or a quality issue that slows future development. E.g. outdated dependency without a known critical CVE, complex function needing refactor, inconsistent error handling.
- 🟢 منخفض (Low): genuine but not urgent. E.g. missing tests on a non-critical path, caching opportunity, inconsistent naming.
- ⚪ للعلم (Info): observations, not problems. E.g. "this pattern repeats 8 times, consider extracting", "no CI configured yet".
Calibrate honestly. Inflating severity destroys trust; mostly low/medium findings is a fine outcome.
Report format (شكل الريبورت)
ALWAYS use this exact template. The report is in Arabic; code, file paths and technical terms stay in their original form. The Arabic headings and bracketed placeholders below are owner-facing output; keep them.
# تقرير التحقق الشامل — [اسم المشروع]
> **تاريخ التحقق:** YYYY-MM-DD
> **نوع المشروع:** [مثال: Node.js REST API + PostgreSQL]
> **التقنيات الأساسية:** [Express 4.x، Sequelize، Redis، …]
> **حجم الكود المفحوص:** [عدد الملفات/أسطر الكود تقريباً]
## الملخص التنفيذي
[فقرة قصيرة 3-5 أسطر: ما هو المشروع، ما هي الحالة العامة، ما هو أهم 2-3 أشياء يجب أن يعرفها صاحب المشروع فوراً.]
**إجمالي المشاكل:** N
- 🔴 حرج: N
- 🟠 عالي: N
- 🟡 متوسط: N
- 🟢 منخفض: N
- ⚪ للعلم: N
**أعلى ثلاث أولويات (افعلها أولاً):**
1. [SEV-XXX] [عنوان المشكلة]
2. [SEV-XXX] [عنوان المشكلة]
3. [SEV-XXX] [عنوان المشكلة]
---
## فهرس المشاكل
| الرقم | الخطورة | الفئة | العنوان | الملف |
|------|---------|------|---------|-------|
| SEV-001 | 🔴 حرج | أمن | … | src/auth.js:42 |
| SEV-002 | 🟠 عالي | أداء | … | src/api/users.js:120 |
| … | … | … | … | … |
---
## المشاكل التفصيلية
### SEV-001 — 🔴 [عنوان المشكلة]
**الفئة:** أمن
**الملف(ات):** `src/auth.js:42-58`
**الخطورة:** حرج
#### 1. المشكلة
[وصف دقيق ومحدد لما هو خطأ. اذكر السلوك الفعلي، وما الذي يجعله مشكلة، وفي أي ظرف يظهر الأثر.]
```[لغة الكود]
// مقتطف الكود المشكل، مع رقم السطر إن أمكن
2. الحل
[الحل الملموس، خطوة بخطوة. لو الحل عبارة عن تعديل كود، اعرض الكود الجديد كاملاً، لا diff فقط.]
// الكود بعد الإصلاح
3. لماذا هذا الحل تحديداً؟
[لماذا اخترت هذا النهج. ما هي البدائل التي فكرت فيها ولماذا تم رفضها. ما هي المقايضات (tradeoffs). إذا كان السياق يبرر حلاً مختلفاً، اذكر ذلك.]
4. كيف نتفادى هذه المشكلة مستقبلاً
[الدرس العام القابل للتطبيق على مشاريع أخرى. ليس مجرد "كن حذراً"، بل: قاعدة محددة، أو أداة ينبغي إضافتها، أو ممارسة هيكلية، أو فحص مؤتمت يمنع تكرار هذا النوع من الخطأ. مثال: "أضف ESLint plugin X"، أو "اجعل كل استعلام يمر عبر طبقة repository"، أو "أضف pre-commit hook لـ secret scanning".]
SEV-002 — 🟠 [العنوان]
[نفس الهيكل]
[… وهكذا لكل المشاكل …]
التوصيات المعمارية العامة
[إذا لاحظت أنماطاً متكررة أو استثمارات تحسينية كبرى لا تناسب صيغة "مشكلة واحدة"، اذكرها هنا في فقرات قصيرة. مثل: "غياب طبقة validation موحدة"، "النظر في فصل الـ domain logic عن طبقة الـ ORM"، إلخ.]
ما لم يتم فحصه
[كن صريحاً بشأن النطاق. مثلاً: "لم يتم فحص ملفات الـ migrations التاريخية"، "لم يتم تشغيل فحص dependencies ضد قاعدة CVE حية".]
---
## Principles
These matter more than any checklist.
1. **Impact over volume.** Five real, well-explained findings beat fifty nitpicks. If you're padding, stop.
2. **Specific, never generic.** Cite `file:line` and show the offending code. "Improve error handling" is useless; "in `src/api/users.js:42` the catch swallows the DB error and returns 200; log and return 500" is useful.
3. **Distinguish bugs, risks, style.** Tag mentally or explicitly: 🐛 Bug (definitely wrong) · ⚠️ Risk (wrong under certain conditions) · 💅 Style (preference). Mostly report bugs and risks; style only with real maintainability impact.
4. **Acknowledge tradeoffs.** A "best practice" isn't universal. If context justifies the current approach, say so or pick another finding. In section 3 ("لماذا هذا الحل") genuinely engage with alternatives; don't just restate the fix.
5. **Verify before claiming.** Unsure it's real? Dig deeper, or mark it: "محتاج تأكيد — يحتمل أن X يحدث في حالة Y". A confidently wrong finding burns more trust than a hedged correct one.
6. **No fabricated findings.** Never invent issues to fill a section. One security finding and eight performance ones is a truthful report.
7. **Prevention must be actionable.** Section 4 is the most valuable part: "be more careful" isn't actionable; "add `eslint-plugin-security`", "move all DB access behind a repository interface", "use parameterized queries everywhere and ban string concatenation in queries via a lint rule" are.
8. **Group repeated mistakes.** The same bug in 12 files = one finding listing 12 locations.
9. **Show new code in full.** In section 2 ("الحل"), show the post-fix code in full, not a hard-to-read diff, so the user can paste it.
10. **Arabic for prose, English for code.** Narrative in Arabic; code blocks, file paths, function/variable names, framework names and standard acronyms (SQL, CSRF, JWT...) stay as-is.
---
## Edge cases
- **Project too large to audit exhaustively.** Say so in the executive summary, then sample strategically: all entry points, auth/authz code, DB access, input handlers, plus a representative sample of the rest. List unreached parts under "ما لم يتم فحصه".
- **Partial project / single file.** Audit what's provided; state that you can only flag what's visible (e.g. missing authorization checks can only be confirmed against surrounding code).
- **No project provided.** Don't make one up; ask the user to share the code (zip, files, or paste).
- **Almost nothing found.** Report honestly; "the project is in good shape; here are 3 minor observations" is valid.
- **Conflicting findings** (e.g. a performance fix that creates a security issue). Note the conflict in section 3 and recommend the path that best fits the project's apparent priorities, or surface the choice to the user.
1---2name: project-audit3description: Comprehensive audit of a code project across security, quality, performance and architecture, producing a structured Arabic Markdown report (problem, fix, why, prevention per finding). Use when asked to audit/review a codebase, find problems or vulnerabilities, or judge production-readiness; also "تحقق" / "فحص" / "مراجعة" / "أوديت شامل" / "code review".4metadata:5 source: https://skillmd.com/skills/khaymah/project-audit6---78# Project Audit (تحقق شامل للمشروع)910Reply in the owner's language (profile; default Egyptian Arabic). The report itself is always written in Arabic.1112## Goal1314Produce one Arabic Markdown file giving the developer:151. An inventory of every real problem (security, code quality, performance, architecture), with no padding and no fabricated issues.162. For each issue: the fix, the reasoning behind it, and a generalizable lesson for future projects.1718The report is the deliverable; everything else exists to make it accurate and useful.1920---2122## Workflow2324Four phases, in order; early phases inform later ones.2526### Phase 1: Reconnaissance (استكشاف المشروع)2728Before opening any source file, map what you're auditing.29301. **List the project tree** (exclude `node_modules/`, `.git/`, `vendor/`, `dist/`, `build/`, `.next/`, `target/`, `__pycache__/`, lock files, other generated/vendored content).312. **Identify the stack**: language(s), framework(s), runtime, database, build system (`package.json`, `requirements.txt`, `Gemfile`, `pom.xml`, `Cargo.toml`, `go.mod`, etc.).323. **Identify the project type**: web API, full-stack app, CLI, library, mobile app, infra config, etc. The type decides which threats matter most.334. **Find entry points**: `main.*`, `index.*`, route definitions, request handlers, CLI parsers, background workers, cron jobs.345. **Find configuration and secret-handling code**: `.env*`, `config/`, settings files, anything reading `process.env` / `os.environ`.3536Output (internal, not in the report): a short stack summary and where the critical code lives. It drives where you spend audit time.3738### Phase 2: Multi-dimensional scan (الفحص متعدد الأبعاد)3940Walk the source files systematically. Run each substantive file past all four pillars while it's open; don't audit one pillar at a time across the whole project (wastes context).4142Excluded: vendored code, generated code, minified bundles, test fixtures (unless they leak secrets), migrations (unless logic-bearing).4344**The four pillars are weighted equally.** Don't let security findings crowd out architectural ones or vice versa; an unmaintainable module is as worth reporting as a missing validation check.4546### Phase 3: Cross-file and deep-dive analysis (التعمّق)4748After the file-by-file scan, look at the project holistically:4950- **Patterns**: the same mistake in many places is one finding, not twenty. Note the pattern and list affected files.51- **Cross-cutting concerns**: authentication, error handling, logging, config loading, database access. Audit them as systems, not individual files.52- **Missing pieces**: what *should* be there but isn't (tests, input validation layer, rate limiting on a public API, error monitoring). Absence is a finding.53- **Dependency hygiene**: outdated packages, known CVEs, abandoned deps, suspiciously rare packages (supply-chain risk).5455### Phase 4: Write the report (كتابة الريبورت)5657Compile findings into the exact format below, in Arabic. Save to `/mnt/user-data/outputs/audit-report.md` (or a descriptive filename if the project has a name) and present it via `present_files`.5859---6061## Audit checklists6263Prompts to *think* about each axis, not boxes to tick; don't force a finding under every bullet.6465### 🔒 Security (الأمن)6667- **Injection**: SQL/NoSQL, command, LDAP, template (SSTI), XPath. Look for string concatenation into queries/commands/templates.68- **Cross-site** (web): XSS (reflected, stored, DOM), CSRF (missing tokens or SameSite), open redirects, clickjacking (missing frame-ancestors / X-Frame-Options).69- **Authentication and sessions**: weak password storage (no bcrypt/argon2/scrypt, low cost), predictable tokens, no session expiry, JWT misuse (`alg: none`, secrets in client, no expiry).70- **Authorization**: missing access checks, IDOR, privilege escalation paths, broken multi-tenancy isolation.71- **Secrets in code**: API keys, DB passwords, private keys, tokens hardcoded or committed; `.env*` files in the tree; default credentials.72- **Cryptography**: MD5/SHA1 for security, ECB mode, hardcoded IVs, custom crypto, weak random (`Math.random`/`rand` for tokens).73- **Input validation**: trusting user input (path traversal, upload type/size checks, deserializing untrusted data: pickle, YAML.load, Java deserialization).74- **Output handling**: unescaped output in HTML/SQL/shell, content-type sniffing, missing or overly permissive CORS (`*` with credentials).75- **Dependencies**: known-vulnerable versions (check advisories), known supply-chain compromises.76- **Insecure defaults**: debug mode in production, verbose error pages leaking stack traces, default admin credentials, permissive file permissions.77- **Logging and secrets**: PII/secrets in logs, full request bodies logged, tokens echoed in errors.7879### 🧹 Code quality (جودة الكود)8081- **Bugs**: off-by-one, null/undefined dereference, async race conditions, bad error handling (swallowed exceptions, catch-all, errors turned into nulls), wrong comparisons (`==` vs `===`, float equality), resource leaks (unclosed files/connections/streams).82- **Error handling**: missing at boundaries (network, filesystem, DB); `null` meaning "error" undocumented; `catch` that logs and continues when it shouldn't; inconsistent error shapes.83- **Dead code and duplication**: unused functions/files/imports, commented-out code, copy-pasted blocks to extract.84- **Complexity**: functions doing too much, deep nesting, long parameter lists, god-objects. Name the worst offenders.85- **Naming and readability**: misleading names (a `validate` that mutates), obscuring abbreviations, inconsistent conventions.86- **Comments and docs**: comments contradicting code (strong bug signal; one is wrong), missing docs on public APIs, stale TODOs/FIXMEs.87- **Type safety**: excessive `any` / `dynamic` / untyped dicts where stronger typing is expected; missing return types on public functions.88- **Tests**: none on critical paths, tests asserting nothing, brittle tests coupled to implementation, flaky time/network tests, no integration tests for important flows.8990### ⚡ Performance (الأداء)9192- **Database**: N+1 queries, missing indexes on filter/join columns, SELECT * in hot paths, no pagination on potentially large results, transactions held open across slow operations.93- **Algorithmic**: O(n²) where O(n) is possible, nested loops over the same large data, sorting in inner loops, recomputing the same value.94- **I/O and blocking**: synchronous I/O in async/event-loop code, blocking the main thread, missing batching (one HTTP request per item instead of bulk).95- **Memory**: loading whole large files instead of streaming, retained references that should be GC'd, large objects needlessly in module scope.96- **Caching**: missing on expensive deterministic computation, missing HTTP cache headers, invalidation bugs.97- **Frontend (if applicable)**: large unsplit bundles, unoptimized images, render-blocking resources, re-renders from unstable references, missing memoization where it matters, hydration mismatches.98- **Network**: chatty APIs (many small calls where one batched call would do), missing compression, missing connection pooling.99100### 🏛️ Architecture (المعمارية)101102- **Separation of concerns**: business logic mixed with framework code, handlers doing data access directly, DB queries in view templates, side effects in pure-looking functions.103- **Coupling**: modules depending on each other's internals, circular dependencies, hidden coupling via shared mutable state.104- **Boundaries**: no clear layer boundaries (domain <-> infrastructure), framework types leaking into the domain (ORM models as API responses without DTOs).105- **Scalability**: in-memory state where horizontal scaling is expected, sticky-session assumptions, shared-filesystem assumptions, no idempotency on side-effectful endpoints.106- **Configuration**: magic numbers, config scattered across files, no environment separation, secrets and feature flags mixed.107- **Dependency direction**: high-level modules depending on low-level ones (rather than both on abstractions), domain depending on infrastructure.108- **Error/result propagation**: exceptions in some places and return values in others without convention; context lost as errors bubble up.109- **Observability**: critical operations without logs, no structured logging, no correlation IDs across async boundaries, no metrics on key business operations.110111---112113## Severity classification (تصنيف الخطورة)114115Use these five levels and emoji prefixes; the report grouping depends on them.116117- 🔴 **حرج (Critical)**: active exploitability, data loss, possible production outage, or a flaw triggerable remotely without authentication. E.g. SQL injection, hardcoded admin password, broken authentication.118- 🟠 **عالي (High)**: real exploitability with prerequisites, or a bug that hits users in production under normal conditions. E.g. IDOR needing an authenticated user, N+1 on a hot endpoint, missing CSRF on a state-changing form.119- 🟡 **متوسط (Medium)**: real but limited impact, or a quality issue that slows future development. E.g. outdated dependency without a known critical CVE, complex function needing refactor, inconsistent error handling.120- 🟢 **منخفض (Low)**: genuine but not urgent. E.g. missing tests on a non-critical path, caching opportunity, inconsistent naming.121- ⚪ **للعلم (Info)**: observations, not problems. E.g. "this pattern repeats 8 times, consider extracting", "no CI configured yet".122123**Calibrate honestly.** Inflating severity destroys trust; mostly low/medium findings is a fine outcome.124125---126127## Report format (شكل الريبورت)128129ALWAYS use this exact template. The report is in Arabic; code, file paths and technical terms stay in their original form. The Arabic headings and bracketed placeholders below are owner-facing output; keep them.130131```markdown132# تقرير التحقق الشامل — [اسم المشروع]133134> **تاريخ التحقق:** YYYY-MM-DD135> **نوع المشروع:** [مثال: Node.js REST API + PostgreSQL]136> **التقنيات الأساسية:** [Express 4.x، Sequelize، Redis، …]137> **حجم الكود المفحوص:** [عدد الملفات/أسطر الكود تقريباً]138139## الملخص التنفيذي140141[فقرة قصيرة 3-5 أسطر: ما هو المشروع، ما هي الحالة العامة، ما هو أهم 2-3 أشياء يجب أن يعرفها صاحب المشروع فوراً.]142143**إجمالي المشاكل:** N144- 🔴 حرج: N145- 🟠 عالي: N146- 🟡 متوسط: N147- 🟢 منخفض: N148- ⚪ للعلم: N149150**أعلى ثلاث أولويات (افعلها أولاً):**1511. [SEV-XXX] [عنوان المشكلة]1522. [SEV-XXX] [عنوان المشكلة]1533. [SEV-XXX] [عنوان المشكلة]154155---156157## فهرس المشاكل158159| الرقم | الخطورة | الفئة | العنوان | الملف |160|------|---------|------|---------|-------|161| SEV-001 | 🔴 حرج | أمن | … | src/auth.js:42 |162| SEV-002 | 🟠 عالي | أداء | … | src/api/users.js:120 |163| … | … | … | … | … |164165---166167## المشاكل التفصيلية168169### SEV-001 — 🔴 [عنوان المشكلة]170171**الفئة:** أمن172**الملف(ات):** `src/auth.js:42-58`173**الخطورة:** حرج174175#### 1. المشكلة176177[وصف دقيق ومحدد لما هو خطأ. اذكر السلوك الفعلي، وما الذي يجعله مشكلة، وفي أي ظرف يظهر الأثر.]178179```[لغة الكود]180// مقتطف الكود المشكل، مع رقم السطر إن أمكن181```182183#### 2. الحل184185[الحل الملموس، خطوة بخطوة. لو الحل عبارة عن تعديل كود، اعرض الكود الجديد كاملاً، لا diff فقط.]186187```[لغة الكود]188// الكود بعد الإصلاح189```190191#### 3. لماذا هذا الحل تحديداً؟192193[لماذا اخترت هذا النهج. ما هي البدائل التي فكرت فيها ولماذا تم رفضها. ما هي المقايضات (tradeoffs). إذا كان السياق يبرر حلاً مختلفاً، اذكر ذلك.]194195#### 4. كيف نتفادى هذه المشكلة مستقبلاً196197[الدرس العام القابل للتطبيق على مشاريع أخرى. ليس مجرد "كن حذراً"، بل: قاعدة محددة، أو أداة ينبغي إضافتها، أو ممارسة هيكلية، أو فحص مؤتمت يمنع تكرار هذا النوع من الخطأ. مثال: "أضف ESLint plugin X"، أو "اجعل كل استعلام يمر عبر طبقة repository"، أو "أضف pre-commit hook لـ secret scanning".]198199---200201### SEV-002 — 🟠 [العنوان]202203[نفس الهيكل]204205---206207[… وهكذا لكل المشاكل …]208209## التوصيات المعمارية العامة210211[إذا لاحظت أنماطاً متكررة أو استثمارات تحسينية كبرى لا تناسب صيغة "مشكلة واحدة"، اذكرها هنا في فقرات قصيرة. مثل: "غياب طبقة validation موحدة"، "النظر في فصل الـ domain logic عن طبقة الـ ORM"، إلخ.]212213## ما لم يتم فحصه214215[كن صريحاً بشأن النطاق. مثلاً: "لم يتم فحص ملفات الـ migrations التاريخية"، "لم يتم تشغيل فحص dependencies ضد قاعدة CVE حية".]216```217218---219220## Principles221222These matter more than any checklist.2232241. **Impact over volume.** Five real, well-explained findings beat fifty nitpicks. If you're padding, stop.2252. **Specific, never generic.** Cite `file:line` and show the offending code. "Improve error handling" is useless; "in `src/api/users.js:42` the catch swallows the DB error and returns 200; log and return 500" is useful.2263. **Distinguish bugs, risks, style.** Tag mentally or explicitly: 🐛 Bug (definitely wrong) · ⚠️ Risk (wrong under certain conditions) · 💅 Style (preference). Mostly report bugs and risks; style only with real maintainability impact.2274. **Acknowledge tradeoffs.** A "best practice" isn't universal. If context justifies the current approach, say so or pick another finding. In section 3 ("لماذا هذا الحل") genuinely engage with alternatives; don't just restate the fix.2285. **Verify before claiming.** Unsure it's real? Dig deeper, or mark it: "محتاج تأكيد — يحتمل أن X يحدث في حالة Y". A confidently wrong finding burns more trust than a hedged correct one.2296. **No fabricated findings.** Never invent issues to fill a section. One security finding and eight performance ones is a truthful report.2307. **Prevention must be actionable.** Section 4 is the most valuable part: "be more careful" isn't actionable; "add `eslint-plugin-security`", "move all DB access behind a repository interface", "use parameterized queries everywhere and ban string concatenation in queries via a lint rule" are.2318. **Group repeated mistakes.** The same bug in 12 files = one finding listing 12 locations.2329. **Show new code in full.** In section 2 ("الحل"), show the post-fix code in full, not a hard-to-read diff, so the user can paste it.23310. **Arabic for prose, English for code.** Narrative in Arabic; code blocks, file paths, function/variable names, framework names and standard acronyms (SQL, CSRF, JWT...) stay as-is.234235---236237## Edge cases238239- **Project too large to audit exhaustively.** Say so in the executive summary, then sample strategically: all entry points, auth/authz code, DB access, input handlers, plus a representative sample of the rest. List unreached parts under "ما لم يتم فحصه".240- **Partial project / single file.** Audit what's provided; state that you can only flag what's visible (e.g. missing authorization checks can only be confirmed against surrounding code).241- **No project provided.** Don't make one up; ask the user to share the code (zip, files, or paste).242- **Almost nothing found.** Report honestly; "the project is in good shape; here are 3 minor observations" is valid.243- **Conflicting findings** (e.g. a performance fix that creates a security issue). Note the conflict in section 3 and recommend the path that best fits the project's apparent priorities, or surface the choice to the user.