/pair-capability-assess-security — Security Assessment

Evaluate and document the project security posture. Follows the resolution cascade: explicit argument wins, then existing adoption, then full assessment from guidelines. Reads package-level .pair.security.md files to avoid duplicating rules already defined in submodules.

Arguments

Argument	Required	Description
$scope	No	Limit assessment to one package: web, mobile, services. Omit for full project assessment.
$choice	No	Override: skip assessment and adopt a specific security control set directly (e.g. owasp-top10).

Composed Skills

Skill	Type	Required
/pair-capability-record-decision	Capability	Yes — records security strategy as ADL

Adoption Files

• Primary target: adoption/tech/security.md — global security principles and WordPress-specific rules
• Package targets (read + write): .pair.security.md files in apps/web/.pair/, apps/mobile/.pair/, services/.pair/
• Ownership: Global principles section (shared file — package-specific rules live in submodule files)

Algorithm

Step 1: Resolution Cascade

Path A — Argument Override

1. Check: Is $choice provided?

2. Skip: If not provided, go to Path B.

3. Act: Confirm with developer:

   Security control override: $choice. This will be adopted without full assessment. Confirm?

4. Check: Does adoption/tech/security.md already exist with different controls?

   • If yes, warn: "Current security adoption exists. Override to $choice?"

5. Verify: Developer confirms. Proceed to Step 4.

Path B — Adoption Exists

1. Check: Does adoption/tech/security.md exist and is it populated (not template)?

2. Skip: If missing or empty, go to Path C.

3. Act: Read current adoption. Read all package .pair.security.md files present. Present:

   Security adoption already exists. Global principles: [list] Package files found: [web | mobile | services] Open vulnerabilities tracked: [count from package files]

4. Check: Does a corresponding decision record exist? (Scan adoption/decision-log/ for *security* files.)

5. Act: If decision record missing, compose /pair-capability-record-decision to backfill.

6. Verify: Adoption and decision record consistent. Done — exit skill.

Path C — Full Assessment

1. Act: Proceed to Step 2 (full assessment mode).

Step 2: Read Guidelines

1. Act: Read security guidelines:
   • Security README — framework overview, tool matrix, severity classification
   • Security Guidelines — OWASP-based standards
   • Security by Design — design principles
   • Authentication & Authorization — identity controls
   • Vulnerability Prevention — proactive controls
   • Sensitive Data — data handling rules
   • API Security — API-specific controls
2. Act: Read project context:
   • adoption/product/PRD.md — project type, scale, compliance requirements (if available)
   • adoption/tech/tech-stack.md — platforms and languages (determines which controls apply)
   • All existing .pair.security.md files — rules already documented per package
3. Verify: Guidelines and project context loaded.

Step 3: Assess Security Posture

1. Act: If $scope is provided, assess only that package. Otherwise assess all packages present.

2. Act: For each package in scope, evaluate against OWASP Top 10 categories:

   • A01 Broken Access Control
   • A02 Cryptographic Failures
   • A03 Injection
   • A04 Insecure Design
   • A05 Security Misconfiguration
   • A06 Vulnerable and Outdated Components
   • A07 Identification and Authentication Failures
   • A08 Software and Data Integrity Failures
   • A09 Security Logging and Monitoring Failures
   • A10 Server-Side Request Forgery

3. Act: Assign severity to each gap found (P0 Critical / P1 High / P2 Medium / P3 Low) using the classification in the security README.

4. Act: Check which package .pair.security.md files already exist:

   • If a file exists, read it and treat documented rules as already addressed — do NOT duplicate them in the global adoption file.
   • If a file is missing for a package with code, flag it as a gap.

5. Act: Present findings summary to developer:

   Security Assessment Summary — [scope]

   OWASP Coverage:

   • A01 Access Control: [OK | gaps found]
   • A02 Cryptographic Failures: [OK | gaps found]
   • ... (all 10 categories)

   Open vulnerabilities by severity:

   • P0 Critical: N
   • P1 High: N
   • P2 Medium: N

   Missing package security files: [list]

   Recommendation: [summary of controls to adopt]

6. Verify: Developer approves the assessment and proposed controls.

Step 4: Write Adoption Files

1. Act: Update adoption/tech/security.md:

   • Write or update Security Principles section with approved global controls.
   • Write or update WordPress-Specific section if WordPress is in scope.
   • Do NOT write package-specific rules — those belong in .pair.security.md submodule files.
   • Preserve existing content in sections not touched by this assessment.

2. Act: For each package missing a .pair.security.md file:

   • Create the file at apps/<package>/.pair/.pair.security.md (or services/.pair/.pair.security.md).
   • Follow the structure of existing package files (open vulnerabilities + security rules + exceptions + what's done correctly + references).
   • Add the new file reference to the Security Review Process section of adoption/tech/security.md.

3. Verify: All adoption files written and consistent. No rule is duplicated between global and package files.

Step 5: Record Decision

1. Act: Compose /pair-capability-record-decision:
   • $type: non-architectural
   • $topic: security-strategy
   • $summary: "Security posture assessed for [scope]: [N] controls adopted, [N] open vulnerabilities tracked"
2. Verify: ADL created at adoption/decision-log/YYYY-MM-DD-security-strategy.md. Adoption file consistent with ADL.

Output Format

ASSESSMENT COMPLETE:
├── Domain:     Security
├── Scope:      [full | web | mobile | services]
├── Path:       [Argument Override | Adoption Exists | Full Assessment]
├── OWASP:      [N/10 categories covered]
├── Open vulns: [P0: N | P1: N | P2: N | P3: N]
├── Adoption:   [adoption/tech/security.md — written | confirmed | updated]
├── Pkg files:  [list of .pair.security.md files created or confirmed]
├── Record:     [ADL path — created | exists | backfilled]
└── Status:     [Complete | Confirmed existing]

Composition Interface

When composed by /pair-process-review:

• Input: /pair-process-review invokes /pair-capability-assess-security during the adoption compliance phase. May pass $scope to limit assessment to the package touched by the PR.
• Output: Returns security findings relevant to the PR — open vulnerabilities, missing controls, OWASP gaps. /pair-process-review includes these findings in the review report.
• ADL is NOT written during review — adoption changes require explicit developer approval outside the review flow.

When invoked independently:

• Full interactive flow. Developer commits changes when satisfied.

Edge Cases

• Package .pair.security.md exists but is outdated (references fixed vulnerabilities): Prompt developer to confirm which items are resolved before updating.
• Argument conflicts with adoption: Warn developer, ask for confirmation. If confirmed, update adoption and create new decision record.
• No PRD available: Proceed with assessment. Warn: "No PRD found — compliance requirements (GDPR, PCI-DSS) must be confirmed manually."
• Package code exists but no .pair.security.md: Create the file. Warn: "No security file found for [package] — creating from assessment findings."
• Decision record already exists for same scope+decision: Skip writing (no duplicates).
• All packages already have .pair.security.md and global adoption exists: Path B (adoption exists) — confirm and exit.

Graceful Degradation

• If security guidelines are not found, use OWASP Top 10 as minimal framework and ask developer to confirm which categories are in scope.
• If /pair-capability-record-decision is not installed, warn and skip decision recording: "Decision not recorded — /pair-capability-record-decision not installed."
• If adoption directory doesn't exist, create it on first write.
• If a package .pair.security.md exists but is empty/template, treat as missing (Path C).

Notes

• Global vs package rules: Global adoption/tech/security.md owns cross-cutting principles. Package .pair.security.md files own implementation-specific rules and open vulnerabilities. Never duplicate a rule in both.
• Security decisions are non-architectural → produce ADL (not ADR), unless the security choice structurally affects the system (e.g. adopting a zero-trust mesh that changes service boundaries).
• Idempotency: the resolution cascade IS the idempotency mechanism. If adoption exists and is consistent with package files, assessment is already done.
• Open vulnerabilities: tracked in package .pair.security.md files under ## Open Vulnerabilities. Once a vulnerability is fixed and a PBI closed, remove it from the file.
• Educational content (OWASP descriptions, threat models, WHY) stays in guidelines. This skill references guidelines for assessment criteria and control recommendations.