@raishin/vanguard-frontier-agentic 2.2.0 → 2.5.0

package/skills/salesforce/salesforce-apex-generator-skill/references/governor-limits.md

@@ -0,0 +1,175 @@
+# Governor Limits Reference
+
+Adapted from forcedotcom/sf-skills generating-apex references (Apache-2.0).
+
+## Key Per-Transaction Limits
+
+| Limit | Synchronous | Asynchronous |
+|---|---|---|
+| SOQL queries | 100 | 200 |
+| SOQL query rows returned | 50,000 | 50,000 |
+| DML statements | 150 | 150 |
+| DML rows processed | 10,000 | 10,000 |
+| CPU time (ms) | 10,000 | 60,000 |
+| Heap size (MB) | 6 | 12 |
+| Callouts (HTTP/SOAP) | 100 | 100 |
+| Queueable jobs enqueued | 50 | 1 (from execute) |
+| Future method calls | 50 | 0 |
+| Batch jobs submitted | 100 | — |
+| Email invocations | 10 | 10 |
+
+---
+
+## Bulkification Patterns
+
+### The Core Pattern: Collect First, Execute Once
+
+**Anti-pattern (SOQL in loop):**
+```apex
+// BAD — hits SOQL limit after 100 iterations
+for (Opportunity opp : opportunities) {
+    Account acc = [SELECT Id, Name FROM Account WHERE Id = :opp.AccountId];
+    // ...
+}
+```
+
+**Correct pattern:**
+```apex
+// GOOD — single SOQL regardless of collection size
+Set<Id> accountIds = new Set<Id>;
+for (Opportunity opp : opportunities) {
+    accountIds.add(opp.AccountId);
+}
+Map<Id, Account> accountMap = new Map<Id, Account>([
+    SELECT Id, Name FROM Account WHERE Id IN :accountIds
+]);
+for (Opportunity opp : opportunities) {
+    Account acc = accountMap.get(opp.AccountId);
+    // ...
+}
+```
+
+### DML Outside Loops
+
+**Anti-pattern:**
+```apex
+// BAD — each insert is a separate DML statement
+for (Contact c : contacts) {
+    insert c; // hits DML limit after 150
+}
+```
+
+**Correct pattern:**
+```apex
+// GOOD — one DML statement for all records
+List<Contact> toInsert = new List<Contact>;
+for (Account acc : accounts) {
+    toInsert.add(new Contact(LastName = 'Test', AccountId = acc.Id));
+}
+insert toInsert;
+```
+
+---
+
+## Async Fallback Strategies
+
+When a synchronous operation would exceed governor limits, use async patterns:
+
+### Pattern 1: Queueable for single async unit
+
+```apex
+// In trigger/service: enqueue instead of executing inline
+if (Limits.getQueueableJobs < Limits.getLimitQueueableJobs) {
+    System.enqueueJob(new ProcessLargeDataSetQueueable(recordIds));
+}
+```
+
+### Pattern 2: Batch for large-volume processing
+
+Threshold: use Batch when processing > 10,000 records or when multiple related
+SOQL/DML operations per record would compound limit usage.
+
+```apex
+Database.executeBatch(new MyDataProcessingBatch, 200);
+// batch size 200 is the default trigger batch size
+```
+
+### Pattern 3: Chunking with chunked Queueables
+
+For recursive or chained processing:
+
+```apex
+public class ChunkedProcessorQueueable implements Queueable {
+    private final List<Id> remaining;
+    private static final Integer CHUNK_SIZE = 100;
+
+    public ChunkedProcessorQueueable(List<Id> ids) {
+        this.remaining = ids;
+    }
+
+    public void execute(QueueableContext ctx) {
+        List<Id> chunk = new List<Id>;
+        for (Integer i = 0; i < Math.min(CHUNK_SIZE, remaining.size); i++) {
+            chunk.add(remaining[i]);
+        }
+        // process chunk
+        List<Id> next = remaining.subList(chunk.size, remaining.size);
+        if (!next.isEmpty) {
+            System.enqueueJob(new ChunkedProcessorQueueable(next));
+        }
+    }
+}
+```
+
+---
+
+## Limit Awareness in Code
+
+Always check limits before triggering async or bulk operations in high-frequency paths:
+
+```apex
+// Check remaining SOQL before proceeding
+if (Limits.getQueries >= 95) {
+    // near limit — log and enqueue for async processing
+    System.enqueueJob(new DeferredProcessingQueueable(ids));
+    return;
+}
+```
+
+Use `Limits` class methods: `Limits.getQueries`, `Limits.getDMLStatements`,
+`Limits.getCpuTime`, `Limits.getHeapSize` for runtime limit introspection.
+
+---
+
+## Large Collection Anti-Patterns
+
+### Avoid Map-of-Lists when Map is sufficient
+
+```apex
+// Wasteful: Map<Id, List<Contact>> when only one Contact per Account expected
+// Better: Map<Id, Contact> with null-check on duplicate
+```
+
+### Avoid SOQL aggregates when a Map covers the use case
+
+```apex
+// Expensive: COUNT SOQL for simple existence checks
+// Better: check map.containsKey(id) after a single IN-query
+```
+
+### Avoid String concatenation in loops (CPU + heap pressure)
+
+```apex
+// BAD
+String result = '';
+for (String s : items) {
+    result += s + ','; // O(n²) string allocation
+}
+
+// GOOD
+List<String> parts = new List<String>;
+for (String s : items) {
+    parts.add(s);
+}
+String result = String.join(parts, ',');
+```

package/skills/salesforce/salesforce-apex-generator-skill/references/security-defaults.md

@@ -0,0 +1,155 @@
+# Apex Security Defaults Reference
+
+Adapted from forcedotcom/sf-skills generating-apex references (Apache-2.0).
+
+## WITH SHARING Default Policy
+
+Every Apex class must declare an explicit sharing model. The default when no keyword is
+present is `without sharing`, which bypasses record-level access — this is a security risk.
+
+**Rule:** Always declare `with sharing` unless there is a documented system-operation
+reason to bypass sharing rules. Never rely on the implicit default.
+
+```apex
+// CORRECT
+public with sharing class AccountService { ... }
+
+// WRONG — implicit without sharing, data exposure risk
+public class AccountService { ... }
+```
+
+---
+
+## USER_MODE for SOQL
+
+`WITH USER_MODE` enforces FLS (Field-Level Security) and CRUD permissions at query time.
+Apply to all SOQL in classes that operate in a user-facing context.
+
+```apex
+// Enforces FLS — user cannot see fields they lack access to
+List<Account> accounts = [
+    SELECT Id, Name, AnnualRevenue
+    FROM Account
+    WHERE OwnerId = :userId
+    WITH USER_MODE
+];
+```
+
+`WITH SYSTEM_MODE` bypasses FLS — only use when the class intentionally operates with
+elevated system privileges (e.g., a background sync class that must read all fields
+regardless of the running user's FLS settings). Document the reason.
+
+---
+
+## Security.stripInaccessible
+
+Use `Security.stripInaccessible` when constructing SObjects from user-supplied data
+or when returning records to untrusted callers. Strips fields the running user cannot
+access according to their profile/permission sets.
+
+```apex
+// Strip inaccessible fields from a user-constructed SObject before DML
+SObjectAccessDecision decision = Security.stripInaccessible(
+    AccessType.CREATABLE,
+    recordsFromUserInput
+);
+insert decision.getRecords;
+
+// Strip on query results before returning to caller
+List<Account> rawAccounts = [SELECT Id, Name, SSN__c FROM Account WITH USER_MODE];
+SObjectAccessDecision readDecision = Security.stripInaccessible(
+    AccessType.READABLE,
+    rawAccounts
+);
+return readDecision.getRecords;
+```
+
+`AccessType` values: `READABLE`, `CREATABLE`, `UPDATABLE`, `UPSERTABLE`.
+
+---
+
+## SOQL Injection Prevention
+
+Never concatenate user input directly into a SOQL string. Always use bind variables.
+
+```apex
+// VULNERABLE
+String query = 'SELECT Id FROM Account WHERE Name = \'' + userInput + '\'';
+List<SObject> results = Database.query(query);
+
+// SAFE — bind variable
+String safeName = userInput;
+List<Account> results = [SELECT Id FROM Account WHERE Name = :safeName];
+
+// SAFE — dynamic SOQL with bind
+String fieldName = 'Name'; // must be from an allowlist, not raw user input
+String query = 'SELECT Id FROM Account WHERE ' + fieldName + ' = :safeName';
+List<SObject> results = Database.query(query, AccessLevel.USER_MODE);
+```
+
+For dynamic SOQL where field/object names come from user input:
+1. Validate against a Schema.getGlobalDescribe allowlist — never trust raw strings
+2. Use `Database.query(query, AccessLevel.USER_MODE)` for FLS enforcement in dynamic SOQL
+
+---
+
+## No Hardcoded IDs or Credentials
+
+Never hardcode Salesforce record IDs, profile IDs, permission set IDs, or credentials
+in Apex code. They break cross-org portability and create maintenance nightmares.
+
+**Prohibited patterns:**
+```apex
+// WRONG
+if (userId == '0053a00000AbCdEfG') { ... }
+String apiKey = 'sk-abc123';
+Id profileId = '00e3a00000AbCdEfG';
+```
+
+**Correct approaches:**
+```apex
+// Custom Metadata Type for config
+My_Config__mdt config = [SELECT API_Key__c FROM My_Config__mdt WHERE Label = 'Integration' LIMIT 1];
+
+// Named Credential for external credentials
+HttpRequest req = new HttpRequest;
+req.setEndpoint('callout:My_Named_Credential/api/endpoint');
+
+// Schema describe for object/field metadata
+Schema.DescribeFieldResult fieldDesc = Schema.SObjectType.Account.fields.getMap.get('Industry').getDescribe;
+
+// Label for user-visible strings
+String message = Label.Account_Updated_Success;
+```
+
+---
+
+## Sensitive Data Handling
+
+- Never log PII (email, phone, SSN, financial data) via `System.debug`.
+- Never store sensitive data in Custom Settings visible to non-admin profiles.
+- Use Named Credentials for external system credentials — never string literals.
+- Use Shield Platform Encryption or Classic Encryption for fields requiring at-rest encryption.
+- Apply `stripInaccessible(AccessType.READABLE)` before returning record collections to
+  any method that may pass data to an untrusted layer.
+
+---
+
+## Permission Checks in Apex
+
+For explicit CRUD checks before DML (in classes that cannot rely on WITH USER_MODE):
+
+```apex
+// Check before insert
+if (!Schema.SObjectType.Account.isCreateable) {
+    throw new AuraHandledException('Insufficient permissions to create Account records.');
+}
+
+// Check before update
+if (!Schema.SObjectType.Account.isUpdateable) {
+    throw new AuraHandledException('Insufficient permissions to update Account records.');
+}
+```
+
+Prefer `WITH USER_MODE` on SOQL and `Security.stripInaccessible` on DML over
+manual permission checks — they are more reliable and less verbose.

package/skills/salesforce/salesforce-apex-log-analyzer-skill/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: salesforce-apex-log-analyzer-skill
+description: "Retrieves and analyzes Apex debug logs from a connected Salesforce org to identify governor-limit hits, SOQL N+1 patterns, unhandled exceptions, and async job failures. T1 read-only runtime — retrieves logs only, never executes code or mutates data. TRIGGER when: user asks to analyze an Apex log, debug a trigger failure, diagnose a governor limit hit, interpret a stack trace from a Salesforce org, or review a DEBUG log for performance issues. Trigger phrases: analyze apex log, debug this trigger, why is my trigger failing, governor limit hit, DEBUG log analysis, check my log file. DO NOT TRIGGER when: user wants to run live tests (use salesforce-apex-test-runner-skill), static code review without logs (use salesforce-apex-lwc-code-review-skill), generating new Apex code (use salesforce-apex-generator-skill), or Agentforce session telemetry (use salesforce-agentforce-stdm-observer-skill)."
+license: MIT
+allowed-tools: Bash(sf apex get log:*) Bash(sf apex tail log:*) Bash(sf data query:*) Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-21"
+  category: operational
+  lifecycle: experimental
+  execution_tier: read-only-runtime
+  mcp_servers: []
+  oauth_scopes: ["api", "refresh_token"]
+  run_as_permissions:
+    required: ["View Setup and Configuration"]
+    denied: ["ModifyAllData", "ViewAllData", "ViewEncryptedData", "ModifyMetadata", "AuthorApex", "ManageConnectedApps"]
+---
+
+# salesforce-apex-log-analyzer-skill
+
+T1 read-only runtime skill for Apex debug log retrieval and analysis. This skill is a
+**diagnostic flashlight** — it retrieves log content, identifies governor-limit hits,
+surfaces SOQL N+1 patterns, traces exceptions, and produces a prioritized finding report.
+It does not execute code, mutate data, or deploy anything.
+
+## When This Skill Owns the Task
+
+Use `salesforce-apex-log-analyzer-skill` when the work requires **log-based diagnosis**:
+
+- "Why is my Account trigger hitting a governor limit?"
+- "Analyze the debug log from my sandbox — it shows a heap size limit"
+- "This trigger is slow — can you read the log and find the SOQL bottleneck?"
+- "I got an unhandled exception in my batch job — here is the log"
+- "Check if my Queueable is completing successfully in the async log"
+- "Retrieve the latest log for user jsmith@myorg.sandbox and diagnose it"
+
+**Delegate elsewhere when:**
+
+| Situation | Skill to use |
+|---|---|
+| User wants to run Apex tests (not read logs) | `salesforce-apex-test-runner-skill` |
+| Static code review without log evidence | `salesforce-apex-lwc-code-review-skill` |
+| Generate a fix for the identified code problem | `salesforce-apex-generator-skill` |
+| Agentforce session traces / parquet telemetry | `salesforce-agentforce-stdm-observer-skill` |
+| SOQL query performance analysis without logs | `salesforce-soql-explorer-skill` |
+
+---
+
+## Required Context to Gather First
+
+Before retrieving or analyzing any log, confirm:
+
+1. **Target org alias** — the `--target-org` value from `sf org list`.
+2. **Log identifier** — log ID, log file path, user/transaction context, or timeframe.
+   Accept a pasted log file if the user provides one directly.
+3. **Transaction context** — which trigger, class, batch job, or user action generated the log.
+4. **Goal** — governor-limit diagnosis, exception trace, performance analysis, or all.
+5. **Sensitivity level** — does the log likely contain PII (email, phone, record data from
+   regulated objects)? Apply stricter redaction if so.
+
+---
+
+## Recommended Workflow
+
+### Step 1 — Verify org alias and reachability
+
+```bash
+sf org display --target-org <alias>
+```
+
+Confirm the org is reachable. Note org type (production vs sandbox) for the audit envelope.
+Apply stricter scrutiny for production org logs — log content may contain PII.
+
+### Step 2 — List available logs
+
+```bash
+sf apex get log --list --target-org <alias>
+```
+
+Identify the relevant log(s) by user, timestamp, and log type. If the user provides a log ID,
+skip this step and proceed to Step 3.
+
+### Step 3 — Retrieve the log
+
+**Option A — specific log by ID:**
+
+```bash
+sf apex get log \
+  --log-id <logId> \
+  --target-org <alias>
+```
+
+**Option B — latest log for current user:**
+
+```bash
+sf apex get log \
+  --number 1 \
+  --target-org <alias>
+```
+
+**Option C — tail live logs (non-blocking diagnostic):**
+
+```bash
+sf apex tail log \
+  --target-org <alias> \
+  --color
+```
+
+**Option D — user has pasted log content directly:**
+Accept the pasted content and proceed to Step 4.
+
+### Step 4 — Parse the log in order
+
+Analyze in this sequence per `references/log-format-reference.md`:
+
+1. **Entry point** — identify transaction type (Apex class invocation, trigger, REST callout, batch execute)
+2. **Fatal errors and unhandled exceptions** — `FATAL_ERROR` and `EXCEPTION_THROWN` lines
+3. **Governor limit hits** — `LIMIT_USAGE_FOR_NS` entries; compare to limits in `references/governor-limit-signatures.md`
+4. **SOQL patterns** — `SOQL_EXECUTE_BEGIN` / `SOQL_EXECUTE_END` pairs; look for repeated queries in loop context
+5. **DML patterns** — `DML_BEGIN` / `DML_END` pairs; check for loop context
+6. **CPU hotspots** — high cumulative CPU entries; identify top consumers
+7. **Heap usage** — `HEAP_ALLOCATE` patterns; identify large collection accumulation
+8. **Async job indicators** — `ENTERING_MANAGED_PKG`, `CALLOUT_REQUEST`, `FUTURE_CALL_PROCESS`
+
+### Step 5 — Classify findings by severity
+
+| Severity | Criteria |
+|---|---|
+| **Critical** | Runtime failure, hard limit hit, unhandled exception, data corruption risk |
+| **Warning** | Near-limit (>75% of a governor limit), non-selective SOQL, slow DML path |
+| **Info** | Optimization opportunity, hygiene issue, async pattern note |
+
+### Step 6 — Apply redaction
+
+Apply all redaction rules (see Redaction Rules section) before emitting any log excerpt
+in output. Never echo raw log lines containing record IDs, user IDs, or PII field values.
+
+### Step 7 — Emit findings with audit envelope
+
+Score findings against the quality rubric (see below). Emit the full audit envelope.
+Propose the smallest correct fix for each Critical and Warning finding.
+
+### Step 8 — Route to repair skill
+
+If a code fix is needed, hand off to `salesforce-apex-generator-skill` with the
+specific finding as context. If a deeper test run is needed, route to
+`salesforce-apex-test-runner-skill`.
+
+---
+
+## Quality Scoring Rubric (100-point)
+
+Score the analysis quality before presenting. Threshold: 80+ acceptable.
+
+| Dimension | Points | What earns full marks |
+|---|---|---|
+| **Governor-limit identification** | 25 | All governor limit hits identified with limit name, current value, and limit ceiling; near-limit warnings included |
+| **Root cause clarity** | 25 | Each finding traces to a specific class, method, and line number; not just "SOQL limit hit" but "AccountSelector.getByOwner line 45 in loop at TriggerHandler line 12" |
+| **SOQL N+1 detection** | 15 | Repeated `SOQL_EXECUTE_BEGIN` entries in loop context identified and the responsible pattern named |
+| **Sanitization quality** | 15 | All record IDs, user IDs, and PII values redacted in output; no raw log lines echoed; audit envelope populated |
+| **Handoff routing** | 10 | Each Critical/Warning finding includes a specific next action and the skill to route to |
+| **Audit envelope** | 10 | All required fields present; log ID hashed if PII risk; timestamp accurate |
+
+**Scoring penalties:**
+- Raw log lines with record IDs echoed: -20 (immediate caveat)
+- Governor limit hit identified but not traced to source: -15
+- SOQL in loop not flagged: -15
+- Missing audit envelope: -15
+- PII field values in output: score voided (immediate reject)
+
+---
+
+## T1 Least-Privilege Contract
+
+This skill operates at T1 — read-only runtime.
+
+- **OAuth scopes:** `api` and `refresh_token` only.
+- **Run As account permissions:**
+  - REQUIRED: `View Setup and Configuration`
+  - DENIED: `ModifyAllData`, `ViewAllData`, `ViewEncryptedData`, `ModifyMetadata`,
+    `AuthorApex`, `ManageConnectedApps`
+- **No View All Data:** Unlike the test runner skill, this skill does NOT require
+  `View All Data`. Log retrieval uses `sf apex get log` which operates under the
+  `View Setup and Configuration` permission scope.
+- **Read-only:** Retrieves log content only. No code execution, no DML, no metadata change.
+- **Log content sensitivity:** Debug logs may contain field values from records processed
+  during the transaction. Apply PII redaction rules strictly.
+
+---
+
+## Audit Envelope Schema
+
+```yaml
+audit_envelope:
+  matter_id: "<caller-provided-or-generated-uuid>"
+  skill_id: "salesforce-apex-log-analyzer-skill"
+  skill_version: "0.1.0"
+  target_org_alias: "<alias>"
+  run_as_user_id: "<user_id_placeholder>"
+  org_type_verified: "sandbox | production | unknown"
+  log_id: "<log-id-or-hash-if-pii-risk>"
+  log_size_bytes: <integer>
+  transaction_entry_point: "<class or trigger name>"
+  timestamp: "<ISO-8601-UTC>"
+  pii_risk_assessed: true | false
+  redactions_applied:
+    - field_or_pattern: "<pattern>"
+      reason: "<record_id|user_id|pii|session_token>"
+  findings_count:
+    critical: <integer>
+    warning: <integer>
+    info: <integer>
+```
+
+---
+
+## Output Format
+
+```yaml
+verdict: "acceptable | caveat | reject"
+quality_score: <0-100>
+quality_notes: "<scoring rationale>"
+
+transaction_summary:
+  entry_point: "<class/trigger/batch>"
+  transaction_type: "<trigger|class|batch|queueable|schedulable|rest>"
+  org_alias: "<alias>"
+  org_type: "sandbox | production | unknown"
+
+findings:
+  critical:
+    - finding: "<title>"
+      location: "<ClassName.method line N>"
+      evidence: "<redacted log excerpt>"
+      governor_limit: "<limit name if applicable>"
+      current_value: <integer>
+      limit_ceiling: <integer>
+      suggested_fix: "<specific remediation>"
+      route_to: "<skill or action>"
+  warning:
+    - finding: "<title>"
+      location: "<ClassName.method line N>"
+      evidence: "<redacted log excerpt>"
+      suggested_fix: "<specific remediation>"
+  info:
+    - finding: "<title>"
+      notes: "<optimization or hygiene note>"
+
+soql_analysis:
+  total_queries: <integer>
+  governor_limit: 100
+  n_plus_1_patterns:
+    - query_excerpt: "<SELECT ... FROM ...>"
+      invocation_count: <integer>
+      loop_context: "<loop location>"
+      suggested_fix: "<move SOQL outside loop; use Map pattern>"
+  non_selective_queries: ["<query excerpt>"]
+
+cpu_analysis:
+  total_cpu_ms: <integer>
+  cpu_limit_ms: 10000
+  hotspots: ["<ClassName.method: N ms>"]
+
+heap_analysis:
+  peak_heap_bytes: <integer>
+  heap_limit_bytes: 6291456
+  large_allocations: ["<description>"]
+
+audit_envelope:
+  <see Audit Envelope Schema>
+
+next_steps:
+  - "<Critical/Warning: route to salesforce-apex-generator-skill for fix>"
+  - "<if tests needed after fix: salesforce-apex-test-runner-skill>"
+
+assumptions:
+  - "<explicit list>"
+
+missing_evidence:
+  - "<what additional log context would help>"
+```
+
+---
+
+## Redaction Rules
+
+Apply in order before emitting any output. Never bypass for any reason.
+
+1. **OAuth tokens, refresh tokens, session IDs:** Never include. Strip from any CLI output.
+2. **Salesforce Org IDs (18-char starting with `00D`):** Replace with `<org_id_placeholder>`.
+3. **Salesforce Record IDs (15/18-char alphanumeric):** Replace with `<record_id_placeholder>`
+   in all log excerpts. Record IDs appear frequently in `USER_DEBUG`, `DML_BEGIN`, and
+   `SOQL_EXECUTE_BEGIN` lines.
+4. **User IDs (OwnerId, CreatedById, Running User ID, User.Id):** Replace with `<user_id_placeholder>`.
+5. **Email addresses in log output:** Replace with `<email_placeholder>` unless the user
+   explicitly acknowledges PII scope and the org is non-production.
+6. **Phone numbers, SSNs, financial account numbers in log output:** Replace with
+   `<pii_placeholder>`. Flag in `redactions_applied`.
+7. **Session tokens and access tokens in USER_DEBUG lines:** Strip entirely. Do not include
+   a placeholder that implies a token value was present.
+8. **Instance URLs:** Replace with org alias in output. Do not emit raw instance URLs.
+9. **Stack traces:** Retain class names and line numbers — required for diagnosis. Replace
+   any record IDs embedded in exception messages.
+
+---
+
+## Handoff Rules
+
+| Finding | Hand off to |
+|---|---|
+| Code fix needed (SOQL in loop, DML pattern, exception handling) | `salesforce-apex-generator-skill` |
+| Test coverage gap surfaced by log | `salesforce-apex-test-generator-skill` |
+| Verification run needed after fix | `salesforce-apex-test-runner-skill` |
+| Permission or FLS finding in log | `salesforce-permission-model-review-skill` |
+| Agentforce / Einstein AI trace in log | `salesforce-agentforce-stdm-observer-skill` |
+| Critical finding needing deployment review | `salesforce-deployment-validator-skill` |
+
+Required handoff fields: `matter_id`, `audit_envelope`, `findings` (sanitized), `next_steps`.
+
+---
+
+## Stop Conditions
+
+Stop and do not continue if:
+
+- Log retrieval fails and the user cannot provide log content directly — stop and explain
+  that a log ID, user context, or pasted log content is required.
+- Log content contains fields identified as encrypted (Shield PE / PMLE) — skip those
+  entries, note the redaction, and analyze the remainder.
+- The audit envelope cannot be completed — stop until matter_id or org alias is resolved.
+- The user requests redaction to be disabled — stop and explain the policy.
+- Log content is from a production org and contains PII fields — apply maximum redaction;
+  if PII is pervasive and the matter classification does not permit, stop and escalate to
+  the compliance specialist.
+
+---
+
+## Security Notes
+
+- **T1 read-only runtime:** No code execution, no DML, no metadata mutation.
+- **No View All Data required:** Log retrieval operates under `View Setup and Configuration`
+  only. This distinguishes this skill from the test runner and reduces its permission footprint.
+- **Log content sensitivity:** Apex debug logs may capture field values, user data, and API
+  payloads. PII and encrypted field redaction is mandatory.
+- **Sanitized output only:** All record IDs, user IDs, session tokens, and PII values
+  redacted before emission. Raw log lines are never echoed.
+- **Structured audit:** Every execution produces a complete audit envelope including
+  `pii_risk_assessed` and `redactions_applied` fields.
+- **Revocable:** Rotating the Run As account's refresh token immediately revokes all access.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `references/log-format-reference.md` | Apex log levels, log line categories (USER_DEBUG, METHOD_ENTRY, SOQL_EXECUTE_BEGIN, LIMIT_USAGE_FOR_NS, FATAL_ERROR, etc.) |
+| `references/governor-limit-signatures.md` | Common governor limit hit patterns, limit ceilings, and remediation strategies |
+| `references/redaction-rules.md` | Detailed redaction patterns for record IDs, user IDs, session tokens, PII field values; jq and grep patterns for automated stripping |