# Fidelity AI Workspace Rules

This repository is a companion workspace for Fidelity iOS work, not the product codebase.

OpenCode should treat this project as a persistent context layer used to:

- keep current project state accurate
- capture durable information from daily work
- draft standups and Mattermost messages
- improve communication for the current manager or stakeholder in natural professional English

## Hot Context

Keep the always-loaded context small. The hot set is:

- `profiles/fidelity/profile.md`
- `agent-memory/behavior/agent-behavior.md`
- `agent-memory/behavior/learning-sessions.md`
- `agent-memory/memory/promotion-rules.md`
- `agent-memory/integrations/technical-verification.md`
- `agent-memory/workflows/ai-to-ai-prompting.md`
- `project-knowledge/00-start/start-here.md`
- `project-knowledge/01-current/current-work.md`
- `project-knowledge/01-current/work-items.md`
- `project-knowledge/03-context/project.md`
- `project-knowledge/03-context/process/communication.md`
- `project-knowledge/03-context/ios/index.md`
- `project-knowledge/03-context/ios/project-swift-guidance.md`
- `project-knowledge/04-people/manager.md`
- `project-knowledge/04-people/index.md`

Load everything else lazily when the task actually needs it.

Do not preemptively load broad context sets, all work-item files, or all process notes unless the current task clearly requires them.

## Required Behavior

- Assume the workspace may contain stale context until checked.
- Treat `project-knowledge/` as the canonical clean project memory for humans and AI. Treat `agent-memory/` as agent operating memory. Treat `ai/inbox/` as raw evidence only.
- Treat `scripts/memory/` as the project-agnostic interface for creating notes, searching memory, querying Bases, and running project knowledge health checks.
- Treat `scripts/obsidian/` as the current Obsidian adapter, not as the core memory abstraction.
- Keep Obsidian Bases clean: templates in `project-knowledge/09-templates/` must not be treated as real notes, and role mapping files such as `project-knowledge/04-people/manager.md` must not be typed as people.
- Maintain useful project-note properties when editing canonical notes, especially work-item relationships (`systems`, `workstreams`, `people`, `related`) and daily note fields (`focus`, `work-items`, `blockers`).
- Before answering questions that depend on current work state, inspect `project-knowledge/01-current/current-work.md` and the latest relevant daily note under `project-knowledge/06-daily/`.
- Prefer lazy loading over eager loading. Pull in only the smallest relevant files for the active task.
- If `ai/inbox/mattermost-latest.md` exists, inspect it for fresher communication context before answering standup, status, or manager-message prompts.
- If the user asks for the latest/last/recent Mattermost message, the latest message from Jeff/current manager, or what someone just said, synchronize Mattermost first instead of relying on existing inbox context.
- If automatic refresh is uncertain, use the explicit latest-message flow: run the Mattermost sync command, then answer from the refreshed inbox only.
- Treat latest-message flows as read-first. Report memory update candidates, but do not edit canonical memory from that command unless the user explicitly asks to promote the fact.
- For learning-style questions, answer from known context and verified facts only; label unknowns, assumptions, and inferences instead of inventing missing details.
- For learning sessions, prioritize durable architecture, process, ownership, debugging strategy, release mechanics, domain concepts, and decision rules over transient ticket status.
- If the user asks what to clarify, ask 3 to 5 high-leverage questions that would help a senior engineer ramp into the project, and include why each matters.
- Ask a concise clarification question when missing context materially changes the answer.
- If the user corrects or teaches the agent during a learning session, update the smallest correct canonical file or behavior surface when that learning should persist.
- For any meaningful prompt, decide whether the interaction introduces or corrects project memory.
- For analysis, review, translation, or drafting requests, answer first unless a memory update is required to avoid losing a clear durable fact.
- Do not create new canonical notes before answering unless the user asked to save the information, the destination is obvious, and the write is small and non-blocking.
- Prefer updating existing canonical files over creating new files during the critical path of a user-facing answer.
- If a sync command, extraction script, or inbox refresh fails, do not update logs, state, or context files from that failed attempt.
- Treat sync failures as operational errors, not project context.
- If a patch or edit verification fails while making a non-essential memory update, stop retrying and return the user-facing answer with the failed target noted.
- `mattermost-sync` should automatically promote high-confidence project facts without asking what to promote.
- Prefer `project-knowledge/06-daily/` as the default destination for new Mattermost-derived facts.
- Promote to `project-knowledge/01-current/current-work.md` only when the fact materially changes active work over the next few days.
- Keep explicit Jira IDs and approved titles visible in `project-knowledge/02-work-items/` and summarize active items in `project-knowledge/01-current/work-items.md` when they are useful for future standups or manager updates.
- Promote to `project-knowledge/03-context/project.md` only when the fact changes durable project understanding.
- When a repeatedly mentioned person becomes relevant to project flow, create or update a file under `project-knowledge/04-people/`.
- Keep role-to-person mapping explicit in `project-knowledge/04-people/manager.md` and the roster in `project-knowledge/04-people/index.md`.
- Never promote tooling chatter, sync status, or generic conversation noise.
- Direct user prompts are also memory sources. Do not limit memory updates to explicit sync commands.
- If a new prompt corrects prior understanding, update the canonical file directly instead of keeping both versions alive.
- Do not ask what should be saved when the correct destination is already clear.
- If the user provides durable new facts, update the appropriate context files instead of leaving the new information only in chat history.
- When the prompt is primarily asking for analysis of a screenshot, message, or document, do not interrupt the answer to perform proactive note creation unless that persistence is the explicit goal.
- When creating a new canonical note from a known type, prefer `scripts/memory/memory.sh create <type> <slug> [title]` so type-to-folder routing stays centralized.
- If the Obsidian CLI adapter fails, fall back to direct Markdown operations and treat the failure as tooling status, not project context.
- If a previous context file is now stale or inaccurate, update that file directly.
- Prefer correcting canonical context over appending contradictory notes.
- Keep changes concise and auditable.
- When the topic is architectural or historical, prefer updating the relevant file under `project-knowledge/03-context/systems/`, `project-knowledge/03-context/workstreams/`, or project-facing `project-knowledge/03-context/process/` instead of overloading `project-knowledge/03-context/project.md`.
- When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `project-knowledge/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 `agent-memory/workflows/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

When drafting or polishing messages:

- use Context, Observation, Action when appropriate
- clarify auth state when relevant
- separate external reports from regressions
- preserve technical meaning while improving English