Skip to content

Development SOP (Seed)

Status: Final draft prepared for handoff (pending review)
Version: 0.9
Owner: BionicLoop engineering
Prepared by: BionicLoop engineering Reviewer: ____
Approver: ____
Decision date: ____
Effective date: ____
Baseline freeze SHA: ____
Applies to: all software changes in this repository Last updated: 2026-04-06 15:05 EDT

Revision History

Version Date Author Summary of Changes
0.1 2026-04-01 Engineering Initial controlled SOP draft
0.9 2026-04-06 BionicLoop engineering Added handoff-ready document-control metadata for the software package

1. Purpose

Define a repeatable process that preserves safety, traceability, and test evidence for an investigational connected-device app.

2. Workflow

  1. Define change scope
  2. Describe intent and impacted modules.
  3. Identify if change is safety-impacting.
  4. Update risk and requirements
  5. Update Docs/Quality/RiskAnalysis.md if risk profile changes.
  6. Add/update SRS-* items in Docs/Quality/SoftwareRequirementsSpecification.md.
  7. Update design record
  8. Update Docs/Quality/SoftwareDesignDescription.md for architecture or behavior changes.
  9. Implement change
  10. Follow Docs/Quality/SoftwareCodingStandard-Swift.md for Swift app/core/test code when applicable.
  11. Keep closed-loop guardrails intact unless explicitly changed by requirement.
  12. Verify
  13. Add/modify tests in line with SVVP.
  14. Run relevant test suites.
  15. Run code-quality verification for merge-intended work:
    • Scripts/run_swift_quality_checks.sh --lint --output-dir <temp dir>
    • Scripts/run_swift_quality_checks.sh --format --output-dir <temp dir>
    • xcodebuild analyze -project BionicLoop.xcodeproj -scheme BionicLoop -destination 'platform=iOS Simulator,name=iPhone 17' -quiet for impacted app/core Swift changes unless the change is docs-only.
  16. Run Xcode automated UI tests for user-facing flow changes when deterministic fixtures are available.
  17. Run screenshot UI review for user-facing changes (see Section 8 checklist) and attach artifacts in STR-* evidence.
  18. Record code review
  19. Update Docs/Quality/CodeReviewLog.md with reviewed commit hash, outcome, findings/fixes, and impacted SRS-* tags (N/A if no requirement impact).
  20. Update traceability
  21. Update Docs/Quality/TraceabilityMatrix.md with requirement/test/evidence mapping.
  22. Document results
  23. Record test outcomes and unresolved risks.
  24. Store evidence artifacts under Docs/Quality/Evidence/STR-*/... and reference that path in bug/trace docs.

3. Minimum PR Gate (Quality)

A PR is not quality-complete unless it includes:

  • requirement linkage (SRS-*)
  • code-review log entry (Docs/Quality/CodeReviewLog.md) with reviewed commit hash and outcome
  • tests (or documented rationale if not feasible)
  • code-quality verification (SwiftLint, SwiftFormat report mode, and xcodebuild analyze when applicable) or documented rationale if not feasible
  • evidence summary
  • traceability update

4. Safety-Critical Change Rules

For runtime, dosing, state persistence, or device-command path changes:

  • require explicit risk review (RA-*)
  • require design note update (SDD-*)
  • require at least one verification artifact reference
  • require reviewer sign-off that behavior matches requirement intent

For Algo2015 C++ or bridge changes specifically: - require TV-ALG-* suite execution per Docs/Planning/Algo2015VerificationPlan.md - require updated structural coverage artifact and uncovered-line rationale (if any) - require STR evidence path update under Docs/Quality/Evidence/STR-ALG-001/...

5. Documentation Sync Rules

When behavior changes, update at minimum:

  • Docs/Architecture/Architecture.md
  • Docs/Requirements/Requirements.md (high-level product requirement view)
  • corresponding Docs/Quality/* artifacts

6. Versioning and Records

  • Keep IDs stable (RA-*, SRS-*, SDD-*, TV-*).
  • Do not renumber historical IDs; mark deprecated if needed.
  • Keep superseded decisions in history (git + changelog notes).

6A. Code Quality Standard Usage

  • Swift app/core/test changes should follow Docs/Quality/SoftwareCodingStandard-Swift.md.
  • If formatter/linter/static-analysis rollout is active for the affected area, execute the required quality lane in addition to tests.
  • Non-functional code-quality cleanup must not be used as cover for behavior changes.
  • For the first cleanup pass in any area, run focused suites before and after the change and run the broader impacted suite after the change.

7. Automated UI Test Usage Rules

  • Use automated UI tests primarily for deterministic verification:
  • routing/navigation
  • setup and dismissal behavior
  • control visibility and enablement
  • state-to-message rendering
  • Do not treat automated UI tests as sufficient evidence for:
  • BLE timing/reliability
  • background wake behavior
  • physical delivery/device-state correctness
  • For any user-facing change, include one of:
  • updated automated UI test coverage, or
  • documented rationale why automation is not feasible and manual/system protocol used instead.

8. Screenshot UI Review Checklist (Required for User-Facing Changes)

Capture screenshots in light and dark modes for changed screens/states, then review and record pass/fail notes.

  • Required states:
  • default state, empty/error state, loading/transitional state, and active/alert state.
  • if the screen has critical actions, include before/after interaction states.
  • Text quality:
  • no clipping, truncation, overlap, or baseline drift.
  • numeric formatting and units are consistent and readable.
  • critical labels/messages are unambiguous and grammatically correct.
  • Layout and spacing:
  • alignment grid is consistent across cards, controls, and labels.
  • safe-area behavior is correct (no accidental edge bleed/occlusion).
  • vertical rhythm and padding are balanced; no collapsed or oversized whitespace.
  • Visual hierarchy and accessibility:
  • primary action and critical status are visually dominant and easy to locate.
  • contrast is adequate in light/dark mode; color is not the sole status cue.
  • hit targets remain usable at standard and larger Dynamic Type sizes.
  • Interaction polish:
  • transitions/animations are smooth, fast, and non-jarring.
  • state changes are obvious and deterministic (no stale text/icons after state updates).
  • Regression scan:
  • verify neighboring controls are unaffected by the change.
  • compare against previous approved screenshot set for unintended visual drift.

Evidence:

  • Store screenshots and review notes in the related STR-* folder.
  • Link the evidence path in Docs/Quality/TraceabilityMatrix.md and any impacted bug/test entries.

9. IDE Submission Preparation Workflow

When operating in IDE submission-prep mode, use the dedicated submission docs as the primary process driver:

  1. Docs/Quality/IDE_Baseline_Freeze_Plan.md
  2. Docs/Quality/IDE_Submission_Readiness_Report.md
  3. Docs/Quality/IDE_Submission_Closure_Checklist.md
  4. Docs/Quality/IDE_Submission_Agent_Brief.md

Additional submission-prep rules:

  • Treat formal evidence as closure evidence; do not close RTM rows on working/dev evidence.
  • Every unresolved requirement or test claim must have explicit disposition and approval metadata.
  • Use objective final-language in controlled docs (accepted, deferred, out of scope) and avoid unresolved provisional phrasing.