Ship

---
name: ship
description: Review and finalize (REVIEWER + DOCUMENTER phases) - runs adversarial code review, commits changes, completes task, and submits reflection to update pattern trust scores.
argument-hint: [task-identifier]
---

<skill name="apex:ship" phase="ship">

<overview>
Final phase: Review implementation with adversarial agents, commit changes, complete task, and submit reflection.

Combines REVIEWER (adversarial code review) and DOCUMENTER (commit, complete, reflect).
</overview>

<phase-model>
phase_model:
  frontmatter: [research, plan, implement, rework, complete]
  rework: enabled
  db_role: [RESEARCH, ARCHITECT, BUILDER, BUILDER_VALIDATOR, REVIEWER, DOCUMENTER]
  legacy_db_role: [VALIDATOR]
source_of_truth:
  gating: frontmatter.phase
  telemetry: db_role
</phase-model>

<phase-gate requires="implement" sets="complete">
  <reads-file>./.apex/tasks/[ID].md</reads-file>
  <requires-section>implementation</requires-section>
  <appends-section>ship</appends-section>
</phase-gate>

<mandatory-actions>
This phase requires THREE mandatory actions in order:
1. **Adversarial Review** - Launch review agents
2. **Git Commit** - Commit all changes
3. **apex_reflect** - Submit pattern outcomes

YOU CANNOT SKIP ANY OF THESE for APPROVE or CONDITIONAL outcomes.
If REJECT, stop after review, set frontmatter to `phase: rework`, and return to `/apex:implement`.
</mandatory-actions>

<initial-response>
<if-no-arguments>
I'll review and finalize the implementation. Please provide the task identifier.

You can find active tasks in `./.apex/tasks/` or run with:
`/apex:ship [identifier]`
</if-no-arguments>
<if-arguments>Load task file and begin review.</if-arguments>
</initial-response>

<workflow>

<step id="1" title="Load task and verify phase">
<instructions>
1. Read `./.apex/tasks/[identifier].md`
2. Verify frontmatter `phase: implement`
3. Parse `<task-contract>` first and note its latest version and any amendments
4. Parse all sections for full context
5. If phase != implement, refuse with: "Task is in [phase] phase. Expected: implement"

Contract rules:
- Final report MUST map changes to AC-* and confirm no out-of-scope work
- If scope/ACs changed during implement, ensure amendments are recorded with rationale and version bump
</instructions>
</step>

<step id="2" title="Gather review context">
<extract>
- `<task-contract>` - Authoritative scope/ACs and amendment history
- `<implementation><files-modified>` - What changed
- `<implementation><files-created>` - What's new
- `<implementation><patterns-used>` - Patterns to validate
- `<implementation><validation-results>` - Test status
- `<implementation><reviewer-handoff>` - Key points for review
- `<plan><architecture-decision>` - Original intentions
- `<plan><warnings>` - Risks to verify mitigated
</extract>

<get-diffs>
```bash
git diff HEAD~N  # or appropriate range for this task's changes
git log --oneline -10
```
</get-diffs>
</step>

<step id="3" title="Phase 1: Launch review agents">
<critical>
Launch ALL 5 Phase 1 agents in a SINGLE message for true parallelism.
</critical>

<agents parallel="true">

<agent type="apex:review:phase1:review-security-analyst">
**Task ID**: [taskId]
**Code Changes**: [Full diff]
**Journey Context**: Architecture warnings, implementation decisions, test results

Review for security vulnerabilities. Return YAML with id, severity, confidence, location, issue, evidence, mitigations_found.
</agent>

<agent type="apex:review:phase1:review-performance-analyst">
**Task ID**: [taskId]
**Code Changes**: [Full diff]
**Journey Context**: Architecture warnings, implementation decisions

Review for performance issues. Return YAML findings.
</agent>

<agent type="apex:review:phase1:review-architecture-analyst">
**Task ID**: [taskId]
**Code Changes**: [Full diff]
**Journey Context**: Original architecture from plan, pattern selections

Review for architecture violations and pattern consistency. Return YAML findings.
</agent>

<agent type="apex:review:phase1:review-test-coverage-analyst">
**Task ID**: [taskId]
**Code Changes**: [Full diff]
**Validation Results**: [From implementation section]

Review for test coverage gaps. Return YAML findings.
</agent>

<agent type="apex:review:phase1:review-code-quality-analyst">
**Task ID**: [taskId]
**Code Changes**: [Full diff]
**Journey Context**: Patterns applied, conventions followed

Review for maintainability and code quality. Return YAML findings.
</agent>

</agents>

<wait-for-all>WAIT for ALL 5 agents to complete before Phase 2.</wait-for-all>
</step>

<step id="4" title="Phase 2: Adversarial challenge">
<agents parallel="true">

<agent type="apex:review:phase2:review-challenger">
**Phase 1 Findings**: [YAML from all 5 Phase 1 agents]
**Original Code**: [Relevant snippets]
**Journey Context**: Plan rationale, implementation justifications

Challenge EVERY finding for:
- Code accuracy (did Phase 1 read correctly?)
- Pattern applicability (does framework prevent this?)
- Evidence quality (Strong/Medium/Weak)
- ROI Analysis:
  - fix_effort: trivial | minor | moderate | significant | major
  - benefit_type: security | reliability | performance | maintainability | correctness
  - roi_score: 0.0-1.0 (benefit / effort ratio)
  - override_decision: pull_forward | keep | push_back
  - override_reason: [Why changing priority]

Return: challenge_result (UPHELD|DOWNGRADED|DISMISSED), evidence_quality, recommended_confidence, roi_analysis
</agent>

<agent type="apex:review:phase2:review-context-defender">
**Phase 1 Findings**: [Findings affecting existing code]
**Repository**: [Path and git info]

Use git history to find justifications for seemingly problematic patterns.
Return: Context justifications for historical code choices.
</agent>

</agents>

<wait-for-all>WAIT for both agents to complete.</wait-for-all>
</step>

<step id="5" title="Synthesize review results">
<confidence-adjustment>
For each finding:
  finalConfidence = phase1Confidence
  finalConfidence *= challengeImpact  # UPHELD=1.0, DOWNGRADED=0.6, DISMISSED=0.2
  finalConfidence *= (0.5 + evidence_score * 0.5)
  if context_justified: finalConfidence *= 0.3
</confidence-adjustment>

<action-decision>
- confidence < 0.3 → DISMISS
- critical AND confidence > 0.5 → FIX_NOW
- high AND confidence > 0.6 → FIX_NOW
- confidence > 0.7 → SHOULD_FIX
- else → NOTE
</action-decision>

<review-decision>
- 0 FIX_NOW → APPROVE (proceed to commit)
- 1-2 FIX_NOW minor → CONDITIONAL (fix or accept with docs)
- 3+ FIX_NOW or critical security → REJECT (return to /apex:implement)
</review-decision>

<reject-flow>
On REJECT:
1. Write `<ship><decision>REJECT</decision>` with a brief rationale
2. Update frontmatter: `phase: rework`, `updated: [ISO timestamp]`
3. STOP. Do NOT commit or call apex_reflect. Return to `/apex:implement`.
</reject-flow>
</step>

<step id="5.5" title="Documentation Updates">
<purpose>
Ensure documentation stays in sync with code changes.
</purpose>

<documentation-checklist>
**If task modified workflow or architecture**:
- [ ] CLAUDE.md - Check for stale references to changed behavior
- [ ] README.md - Update any affected workflow descriptions
- [ ] Related design docs - Search in docs/ directory

**If task modified API or CLI**:
- [ ] API documentation files
- [ ] CLI command documentation
- [ ] Usage examples in docs

**If task modified data structures**:
- [ ] Type definition docs
- [ ] Schema documentation
- [ ] Migration notes if breaking change

**Search strategy**:
```bash
# Find docs that might reference changed files
for file in [modified_files]; do
  grep -r "$(basename $file .ts)" docs/ README.md CLAUDE.md
done
```
</documentation-checklist>

<update-procedure>
1. Search for references to modified code
2. Read each found doc FULLY
3. Update outdated references
4. Verify accuracy after update
5. Add to git staging for commit
</update-procedure>

<docs-to-update-output>
Record in `<implementation><docs-updated>`:
```xml
<docs-updated>
  <doc path="[path]" reason="[Why updated]"/>
</docs-updated>
```
</docs-to-update-output>
</step>

<step id="6" title="Git commit">
<critical>
Commit BEFORE apex_reflect - reflection validates git evidence.
</critical>

<commands>
```bash
git status --short
git add [relevant files]
git commit -m "[Task ID]: [Description]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"
git log -1 --oneline  # Capture commit SHA
```
</commands>

<checkpoint>Commit SHA captured for evidence.</checkpoint>
</step>

<step id="7" title="apex_task_complete">
<call>
```javascript
apex_task_complete({
  id: taskId,
  outcome: "success" | "partial" | "failure",
  key_learning: "Main lesson from this task",
  patterns_used: ["PAT:ID:FROM:PLAN"]  // Only patterns from plan
})
```
</call>

<returns>ReflectionDraft - use as basis for apex_reflect</returns>
</step>

<step id="8" title="apex_reflect">
<critical>
YOU MUST CALL apex_reflect. THIS IS NOT OPTIONAL.

Without apex_reflect:
- Pattern trust scores don't update
- Learnings aren't captured
- Future tasks don't benefit
</critical>

<format-choice>
**batch_patterns** (simple, for most cases):
```javascript
apex_reflect({
  task: { id: taskId, title: taskTitle },
  outcome: "success",
  batch_patterns: [
    {
      pattern: "PAT:ID",  // Must exist in plan's pattern list
      outcome: "worked-perfectly",
      notes: "Optional notes about usage"
    }
  ]
})
```

**claims** (advanced, for new patterns/anti-patterns/learnings):
```javascript
apex_reflect({
  task: { id: taskId, title: taskTitle },
  outcome: "success",
  claims: {
    // Patterns used from plan (updates trust scores)
    patterns_used: [{
      pattern_id: "PAT:ID",
      evidence: [{
        kind: "git_lines",
        file: "src/auth.ts",
        sha: "HEAD",  // or commit SHA
        start: 45,
        end: 78
      }]
    }],

    // Trust score updates (required for patterns_used)
    trust_updates: [{
      pattern_id: "PAT:ID",
      outcome: "worked-perfectly"
    }],

    // NEW patterns discovered during implementation
    new_patterns: [{
      title: "Error Boundary Pattern",
      summary: "Wrap async operations with consistent error handling",
      snippets: [{
        snippet_id: "error-boundary-1",
        source_ref: {
          kind: "git_lines",
          file: "src/utils/errors.ts",
          sha: "HEAD",
          start: 10,
          end: 35
        }
      }],
      evidence: []
    }],

    // Anti-patterns to AVOID
    anti_patterns: [{
      title: "Direct Database Access in Handler",
      reason: "Bypasses transaction management and audit logging",
      evidence: [{
        kind: "git_lines",
        file: "src/handlers/user.ts",
        sha: "HEAD",
        start: 100,
        end: 110
      }]
    }],

    // General learnings
    learnings: [{
      assertion: "JWT refresh tokens require httpOnly cookies for security",
      evidence: [{
        kind: "git_lines",
        file: "src/auth/tokens.ts",
        sha: "HEAD",
        start: 50,
        end: 65
      }]
    }]
  }
})
```
</format-choice>

<evidence-kinds>
| Kind | Required Fields | When to Use |
|------|-----------------|-------------|
| `git_lines` | file, sha, start, end | Code at specific lines |
| `commit` | sha | Entire commit as evidence |
| `pr` | number, repo | Pull request reference |
| `ci_run` | id, provider | CI/CD run evidence |
</evidence-kinds>

<valid-outcomes>
- "worked-perfectly" → 100% success (alpha: 1.0, beta: 0.0)
- "worked-with-tweaks" → 70% success (alpha: 0.7, beta: 0.3)
- "partial-success" → 50% success (alpha: 0.5, beta: 0.5)
- "failed-minor-issues" → 30% success (alpha: 0.3, beta: 0.7)
- "failed-completely" → 0% success (alpha: 0.0, beta: 1.0)
</valid-outcomes>

<common-errors>
1. **Mixing formats**: Use batch_patterns OR claims, not both
2. **Missing SHA**: Always include sha (use "HEAD" if current)
3. **Fabricated patterns**: Only claim patterns from plan
4. **Not committing first**: Evidence validation fails without commit
</common-errors>
</step>

<step id="9" title="Write ship section to task file">
<output-format>
Append to `<ship>` section:

```xml
<ship>
<metadata>
  <timestamp>[ISO]</timestamp>
  <outcome>success|partial|failure</outcome>
  <commit-sha>[SHA]</commit-sha>
</metadata>

<review-summary>
  <phase1-findings count="X">
    <by-severity critical="N" high="N" medium="N" low="N"/>
    <by-agent security="N" performance="N" architecture="N" testing="N" quality="N"/>
  </phase1-findings>
  <phase2-challenges>
    <upheld>N</upheld>
    <downgraded>N</downgraded>
    <dismissed>N</dismissed>
  </phase2-challenges>
  <false-positive-rate>[X%]</false-positive-rate>
</review-summary>

<contract-verification>
  <contract-version>[N]</contract-version>
  <amendments-audited>[List amendments or "none"]</amendments-audited>
  <acceptance-criteria-verification>
    <criterion id="AC-1" status="met|not-met">[Evidence or exception]</criterion>
  </acceptance-criteria-verification>
  <out-of-scope-check>[Confirm no out-of-scope work slipped in]</out-of-scope-check>
</contract-verification>

<action-items>
  <fix-now>
    <item id="[ID]" severity="[S]" confidence="[C]" location="[file:line]">
      [Issue and fix]
    </item>
  </fix-now>
  <should-fix>[Deferred items]</should-fix>
  <accepted>[Accepted risks with justification]</accepted>
  <dismissed>[False positives with reasons]</dismissed>
</action-items>

<commit>
  <sha>[Full SHA]</sha>
  <message>[Commit message]</message>
  <files>[List of files]</files>
</commit>

<reflection>
  <patterns-reported>
    <pattern id="PAT:X:Y" outcome="[outcome]"/>
  </patterns-reported>
  <key-learning>[Main lesson]</key-learning>
  <apex-reflect-status>submitted|failed</apex-reflect-status>
</reflection>

<final-summary>
  <what-was-built>[Concise description]</what-was-built>
  <patterns-applied count="N">[List]</patterns-applied>
  <test-status passed="X" failed="Y"/>
  <documentation-updated>[What docs changed]</documentation-updated>
</final-summary>
</ship>
```
</output-format>

<update-frontmatter>
For APPROVE or CONDITIONAL only:
Set `phase: complete`, `status: complete`, and `updated: [ISO timestamp]`
</update-frontmatter>
</step>

<step id="10" title="Final report to user">
<template>
✅ **Task Complete**: [Title]

📊 **Metrics**:
- Complexity: [X]/10
- Files modified: [N]
- Files created: [N]
- Tests: [passed]/[total]

💬 **Summary**: [Concise description of what was built]

📚 **Patterns**:
- Applied: [N] patterns
- Reflection: ✅ Submitted

✅ **Acceptance Criteria**:
- AC-* coverage: [met|not met with exceptions]

🔍 **Review**:
- Phase 1 findings: [N]
- Dismissed as false positives: [N] ([X]%)
- Action items: [N] (all resolved)

⏭️ **Next**: Task complete. No further action required.
</template>
</step>

</workflow>

<completion-verification>
BEFORE reporting to user, verify ALL actions completed:

- [ ] Phase 1 review agents launched and returned?
- [ ] Phase 2 challenge agents launched and returned (with ROI analysis)?
- [ ] Documentation checklist completed?
- [ ] Contract verification completed (AC mapping + out-of-scope check)?
- [ ] Git commit created? (verify with git log -1)
- [ ] apex_task_complete called? (received ReflectionDraft?)
- [ ] apex_reflect called? (received ok: true?)

**If ANY unchecked → GO BACK AND COMPLETE IT.**
</completion-verification>

<success-criteria>
- Adversarial review completed (7 agents: 5 Phase 1 + 2 Phase 2)
- ROI analysis included in challenger findings
- Documentation checklist completed (grep → read → update → verify)
- Contract verification completed with AC mapping and scope confirmation
- All FIX_NOW items resolved (or explicitly accepted)
- Git commit created with proper message
- apex_task_complete called
- apex_reflect called with proper format (batch_patterns or claims)
- Task file updated with complete ship section
- Frontmatter shows phase: complete, status: complete
</success-criteria>

</skill>