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

.opencode/agents/fidelity.md

@@ -58,5 +58,8 @@ Behavior rules:
 - Do not over-promote uncertain information. Keep uncertain items in the daily log.
 - When drafting communication, preserve technical meaning and improve clarity in natural US English.
 - When answering Swift/iOS programming questions, use the project-local iOS skills and `vault/03-context/ios/`.
+- When answering programming, dependency-management, package-manager, CI/build, testing, or architecture-practice questions, verify with primary/current documentation when the topic may be outdated, disputed, version-sensitive, or project-critical.
+- For CocoaPods, podspecs, private spec repos, trunk/CDN behavior, SPM, Xcode, Swift, and Apple frameworks, do not rely only on model memory before giving strong advice.
 - When generating prompts for GitHub Copilot or another AI, use `vault/03-context/process/ai-to-ai-prompting.md` and the `copilot-prompt-engineering` skill.
 - If the answer depends on current Apple APIs or Xcode/iOS behavior, verify with official Apple or Swift documentation before presenting it as current best practice.
+- Act as an agent, not only as a chat assistant: when a repeated weakness appears in output quality, proactively suggest or apply a workspace-level improvement.

.opencode/agents/workspace.md

@@ -31,6 +31,8 @@ Behavior rules:
 - If an integration or sync command fails, do not update project memory from that failure.
 - Do not promote tooling noise, empty syncs, dependency failures, or generic chat chatter unless the user explicitly asks to track tooling work.
 - Prefer generic `AIW_*` integration variables and support project-specific aliases only when declared by the active profile.
+- For technical advice about programming concepts, dependency tooling, package managers, CI/build systems, testing frameworks, or changing best practices, verify against primary/current documentation before making strong claims.
+- Treat recurring quality gaps as workspace-maintenance signals and update commands, agents, skills, prompts, or process notes when the improvement should persist.
 - When drafting communication, preserve technical meaning, state scope clearly, and write in natural professional English.
 
 Memory destinations:

.opencode/commands/fidelity-context.md

@@ -21,6 +21,7 @@ Use these files as the baseline context:
 @vault/07-maps/people.md
 @vault/03-context/project.md
 @vault/03-context/process/communication.md
+@vault/03-context/process/technical-verification.md
 @vault/03-context/process/ai-to-ai-prompting.md
 @vault/03-context/process/jira-story-rules.md
 @vault/03-context/process/workspace-model.md

.opencode/commands/swift-help.md

@@ -9,6 +9,7 @@ Read:
 @vault/03-context/ios/index.md
 @vault/03-context/ios/current-practices.md
 @vault/03-context/ios/project-swift-guidance.md
+@vault/03-context/process/technical-verification.md
 @vault/03-context/project.md
 @vault/03-context/systems/index.md
 @vault/03-context/workstreams/index.md
@@ -23,7 +24,7 @@ Instructions:
 - Use the `ios-swift-answering` skill if available.
 - Use `swiftui-xflow-review` if the question touches SwiftUI, XFlow, UIKit bridge removal, modal presentation, lifecycle, or backend-driven UI.
 - Use `ios-testing-strategy` if the question touches tests or validation.
-- If current Apple API behavior matters, verify against official Apple or Swift documentation before making strong claims.
+- If current Apple API, Swift, CocoaPods, SPM, Xcode, CI/build, or testing behavior matters, verify against official/primary documentation before making strong claims.
 - Contextualize the answer to Fidelity only when it materially changes the recommendation.
 - Separate current best practice from project-safe recommendation when they differ.
 

.opencode/commands/workspace-context.md

@@ -25,6 +25,7 @@ Read active workspace memory:
 @vault/07-maps/people.md
 @vault/03-context/project.md
 @vault/03-context/process/communication.md
+@vault/03-context/process/technical-verification.md
 @vault/03-context/process/context-maintenance.md
 @vault/03-context/process/workspace-model.md
 @vault/03-context/process/agent-memory-rules.md

.opencode/skills/ios-swift-answering/SKILL.md

@@ -13,7 +13,7 @@ Use this skill for Swift, SwiftUI, iOS architecture, concurrency, testing, or de
 1. Identify whether the question is general Swift/iOS or Fidelity-specific.
 2. Read `vault/03-context/ios/current-practices.md` for currentness rules.
 3. Read `vault/03-context/ios/project-swift-guidance.md` when the answer may affect XFlow, Fid4, XFlowViewMaker, FTFrameworks, feature flags, or consumer validation.
-4. If the answer depends on current Apple APIs, Xcode versions, or migration guidance, verify with official Apple/Swift documentation before making strong claims.
+4. If the answer depends on current Apple APIs, Xcode versions, dependency tooling, package-manager behavior, testing frameworks, or migration guidance, verify with official/primary documentation before making strong claims.
 5. Separate:
    - current best practice
    - project-safe recommendation
@@ -24,4 +24,5 @@ Use this skill for Swift, SwiftUI, iOS architecture, concurrency, testing, or de
 - Be direct and senior-engineer practical.
 - Avoid generic architecture advice when project constraints matter.
 - Do not assume deployment target, Xcode version, or framework migration status.
+- Do not characterize CocoaPods, SPM, podspec repos, trunk/CDN behavior, CI/build behavior, or testing framework practices as good or bad practice without corroborating current primary docs when the recommendation matters.
 - Mention tradeoffs and validation path when relevant.

AGENTS.md

@@ -24,6 +24,7 @@ The detailed operating rules live in:
 - `vault/03-context/systems/index.md`
 - `vault/03-context/workstreams/index.md`
 - `vault/03-context/process/communication.md`
+- `vault/03-context/process/technical-verification.md`
 - `vault/03-context/process/ai-to-ai-prompting.md`
 - `vault/03-context/process/workspace-model.md`
 - `vault/03-context/process/memory-promotion-rules.md`
@@ -73,8 +74,11 @@ These are also loaded through `opencode.json`.
 - Keep changes concise and auditable.
 - When the topic is architectural or historical, prefer updating the relevant file under `vault/03-context/systems/`, `vault/03-context/workstreams/`, or `vault/03-context/process/` instead of overloading `vault/03-context/project.md`.
 - When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `vault/03-context/ios/` and the local OpenCode iOS skills before answering.
+- When the user asks about programming concepts, dependency tooling, package managers, CI/build tooling, testing frameworks, or practices that may be outdated or opinion-sensitive, verify against primary/current documentation before making strong claims.
+- For CocoaPods, podspecs, private specs repos, trunk/CDN behavior, Swift Package Manager, Xcode, Swift, Apple frameworks, and similar project-linked tooling, do not rely only on memory.
 - When the user asks for a prompt for another AI, GitHub Copilot, or the Fidelity development machine, use `vault/03-context/process/ai-to-ai-prompting.md` and generate a self-contained prompt.
 - If a Swift/iOS recommendation depends on current Apple APIs, Xcode behavior, or framework migration guidance, verify against official Apple or Swift documentation before making strong claims.
+- Be aware that this is an agentic workspace. If a recurring gap appears in answers, propose and when appropriate apply a workspace improvement to commands, agents, skills, prompts, or process notes.
 
 ## Communication
 

core/memory/operational-memory.md

@@ -172,3 +172,12 @@ Examples:
 - memory routing correction -> update memory rules and context-maintenance guidance
 
 The daily log may preserve evidence, but reusable behavior must live in the command, prompt, skill, agent, or knowledge file that enforces it.
+
+The agent should also identify recurring quality gaps proactively. If an answer reveals that the workspace lacks a rule, source anchor, command behavior, skill guidance, or memory model needed for better future output, the agent should propose the improvement and apply it when the correct destination is clear.
+
+For technical topics, recurring gaps often belong in:
+
+- domain-specific guidance under `vault/03-context/`
+- reusable skills under `.opencode/skills/`
+- agent behavior rules under `.opencode/agents/` or `AGENTS.md`
+- source anchors for official/current documentation

opencode.json

@@ -60,6 +60,7 @@
     "./vault/07-maps/people.md",
     "./vault/03-context/project.md",
     "./vault/03-context/process/communication.md",
+    "./vault/03-context/process/technical-verification.md",
     "./vault/03-context/process/ai-to-ai-prompting.md",
     "./vault/03-context/process/jira-story-rules.md",
     "./vault/03-context/process/context-maintenance.md",

vault/00-start/start-here.md

@@ -73,6 +73,7 @@ If you are new to this project, read:
 - [Agent Memory Rules](../03-context/process/agent-memory-rules.md)
 - [Memory Promotion Rules](../03-context/process/memory-promotion-rules.md)
 - [Communication Rules](../03-context/process/communication-rules.md)
+- [Technical Verification](../03-context/process/technical-verification.md)
 - [Context Maintenance](../03-context/process/context-maintenance.md)
 - [Workspace Architecture](workspace-architecture.md)
 - Memory interface: `scripts/memory/`

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.