feat: Enhance technical verification processes and documentation for improved accuracy in engineering advice

vault/03-context/ios/current-practices.md

@@ -32,6 +32,25 @@ Avoid relying only on memory for:
 - Swift Testing availability or migration advice
 - Swift concurrency behavior
 - Xcode or iOS version-specific recommendations
+- CocoaPods, podspec, private specs repo, trunk/CDN, or dependency-resolution behavior
+- Swift Package Manager migration or package-resolution behavior
+- CI/build tooling behavior that may depend on current toolchain versions
+- claims that something is a "bad practice" when the answer depends on ecosystem status, migration cost, or project constraints
+
+---
+
+## Technical Verification Rule
+
+For programming concepts tied to project decisions, the agent should behave like a senior engineer:
+
+- distinguish stable engineering principles from ecosystem-specific guidance
+- verify current tool behavior with primary documentation when the topic is version-sensitive
+- separate general best practice from project-safe recommendation
+- avoid blanket statements such as "CocoaPods is bad practice" without context
+- explain tradeoffs: maintenance status, migration cost, consumer integration risk, release propagation, and validation path
+- suggest workspace improvements when a recurring answer-quality gap appears
+
+For Fidelity, dependency tooling is project-relevant because XFlowSDK, XFlowViewMaker, FTFrameworks, and Fid4 integration can depend on published versions, podspec repos, release propagation, and consumer validation.
 
 ---
 
@@ -69,3 +88,7 @@ Avoid relying only on memory for:
 - Swift Testing: `https://developer.apple.com/documentation/testing`
 - XCTest: `https://developer.apple.com/documentation/xctest`
 - Swift language: `https://developer.apple.com/swift/`
+- CocoaPods Build with CocoaPods: `https://guides.cocoapods.org/making/`
+- CocoaPods Specs and Specs Repo: `https://guides.cocoapods.org/making/specs-and-specs-repo.html`
+- CocoaPods Private Pods: `https://guides.cocoapods.org/making/private-cocoapods`
+- CocoaPods trunk read-only plan: `https://blog.cocoapods.org/CocoaPods-Specs-Repo/`

vault/03-context/ios/project-swift-guidance.md

@@ -45,4 +45,6 @@ Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker
 - If the user asks about a code change, separate modern best practice from what is safe for the current project.
 - If codebase constraints are unknown, say what must be confirmed: deployment target, Xcode version, module ownership, feature flag path, and consumer validation path.
 - If the work touches dependency propagation, published specs, or consumer upgrade behavior, explicitly include CocoaPods and podspec-repo reasoning instead of treating them as secondary operational noise.
+- If the user asks whether CocoaPods, podspec repositories, or dependency propagation is good/bad practice, corroborate with current CocoaPods/Apple/Swift documentation and then adapt the recommendation to Fidelity's release path.
+- Do not recommend replacing CocoaPods with SPM just because SPM is modern; first identify current integration constraints, private specs usage, release ownership, consumer app expectations, and migration cost.
 - For manager-ready explanations, connect the technical recommendation to scope, risk, and validation.

vault/03-context/process/index.md

@@ -14,6 +14,9 @@ tags:
 - [communication.md](./communication.md)
   How to frame technical updates and external communication.
 
+- [technical-verification.md](./technical-verification.md)
+  How to verify current engineering concepts and avoid stale best-practice claims.
+
 - [ai-to-ai-prompting.md](./ai-to-ai-prompting.md)
   How to generate prompts for GitHub Copilot or another AI on the Fidelity development machine.
 

vault/03-context/process/technical-verification.md

@@ -0,0 +1,83 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-17
+tags:
+  - process
+  - engineering
+  - verification
+---
+# Technical Verification
+
+## Goal
+
+Ensure the agent gives senior-engineer technical advice instead of relying on stale model memory or generic best-practice claims.
+
+---
+
+## When To Verify
+
+Verify against primary/current documentation before making strong claims about:
+
+- dependency managers and package managers
+- CocoaPods, podspecs, private specs repos, trunk/CDN behavior, and migration strategy
+- Swift Package Manager behavior or migration strategy
+- Xcode, Swift, SwiftUI, Swift concurrency, Swift Testing, XCTest, or Apple framework behavior
+- CI/build systems and release propagation
+- security, authentication, networking, or migration practices
+- any claim that a pattern is a bad practice when project constraints may change the recommendation
+
+---
+
+## Source Priority
+
+Prefer:
+
+- official vendor documentation
+- language or framework documentation
+- official migration guides
+- source repository documentation when it is the canonical project source
+- current project memory when the question is project-specific
+
+Use blogs, forum posts, or third-party guides only as supporting context, not as the primary basis for a strong recommendation.
+
+---
+
+## Answering Pattern
+
+For technical recommendations:
+
+1. State what is known from workspace context.
+2. Verify current external behavior when the topic is version-sensitive or disputed.
+3. Separate general best practice from project-safe recommendation.
+4. Explain tradeoffs and validation path.
+5. If context is missing, ask the smallest material clarification question.
+
+---
+
+## Bad Practice Claims
+
+Avoid blanket claims such as:
+
+- "CocoaPods is bad practice"
+- "SPM is always better"
+- "This architecture is an anti-pattern"
+- "This should be removed"
+
+Instead explain:
+
+- what risk the pattern introduces
+- whether the risk is current or theoretical
+- whether the project has constraints that justify it
+- what a safer migration path would look like
+
+---
+
+## Agentic Self-Improvement
+
+The agent should be aware it is maintaining a workspace, not just answering chat prompts.
+
+If a conversation reveals a recurring gap in technical quality, source verification, command behavior, or memory routing, the agent should propose or apply a workspace improvement in the correct file.
+
+Do not store tool failures or one-off uncertainty as project facts. Store reusable rules and source anchors when they improve future technical answers.