david.delagneau/fidelity-ai-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Organize context files and enhance documentation for clarity and structure

Browse Source
This commit is contained in:
David Delagneau
2026-04-10 08:57:00 -06:00
parent 26f54ed302
commit ae9e69bd4b
38 changed files with 620 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
ai/context/project.md
View File

@@ -17,81 +17,47 @@ The product work happens outside this repository, usually from another machine.
---
## Current Priorities
## Stable Context Map
### REST migration
- Core systems live under:
- `ai/context/systems/`
- Durable workstreams live under:
- `ai/context/workstreams/`
- Stable communication and maintenance rules live under:
- `ai/context/process/`
- Named people and role mapping live under:
- `ai/context/people/`
- REST is behind a feature flag
- GraphQL is still the default fallback
- REST should never be assumed active unless confirmed
- Migration must preserve behavior while Apollo is deprecated safely
### Discourse and AO issues
- External reports are often incomplete
- Many reported issues are not confirmed regressions
- Some issues reproduce only with authenticated users
### Flow debugging
- XFlow behavior changes based on backend configuration
- Entry point affects what the user sees
- Authentication state affects reproducibility
### Testing complexity
- Around 15 entry points have been identified at code level
- Not all entry points are reachable from visible UI
- Validation often requires exploratory testing
## Historical Slack patterns
- XFlow SwiftUI migration discussions repeatedly covered Next-button visibility, markdown modal presentation, and custom nav pin/unpin behavior
- Some historical pipeline failures were traced to Apex/ApexKit or Swift preview macro support in the consuming pipeline, not just XFlow itself
- Jeff often requested explicit, polished wording for PR descriptions and cross-team messages
- Historical discussions also surfaced recurring uncertainty around XFlow ownership boundaries versus consumer-app responsibility
- Cross-team dependency issues sometimes involved security, token access, or external pipeline configuration rather than only iOS code changes
- Historical AO and consumer bugs often turned out to be service/configuration issues, incomplete reproduction reports, or consuming-app integration issues rather than XFlow regressions
- Historical integration work repeatedly involved XFlowViewMaker, FTBusiness, FTFrameworks, and Fid4 release/version coupling, especially when validating fixes in real consumer flows
The Slack archive has already been curated into those files so the agent does not need to rediscover the same patterns from raw history every session.
---
## How This Workspace Is Used
## Current Priorities
- REST migration is replacing GraphQL over time, but REST is still behind a feature flag
- AO and Discourse issues require careful classification because many are incomplete, external, or auth-dependent
- XFlow debugging remains dynamic because behavior changes by entry point, authentication state, backend configuration, and consumer integration
- Consumer validation often depends on Fid4, FT modules, and version propagation, not just SDK behavior
---
## Workspace Use
This machine is used to:
- maintain current project context
- record findings from work performed elsewhere
- capture Mattermost communication that changes understanding
- capture communication that changes technical understanding
- prepare polished updates for the current manager or stakeholder
- generate standups with better context coverage
This means logs must capture both technical findings and communication context.
This means the context files should hold durable engineering knowledge, while `ai/logs/` and `ai/state/` hold the moving day-to-day view.
---
## People Context
## First Files To Read
- The current manager role is mapped in `ai/context/people/manager.md`
- The active people roster lives in `ai/context/people/index.md`
- Repeatedly relevant named people should have individual files under `ai/context/people/`
---
## Communication Expectations
All important updates should clarify:
- whether the flow is authenticated or non-authenticated
- whether the issue is reproducible
- whether the report is external behavior or regression
- whether behavior is present in main
- what action is needed next
Avoid phrases that hide scope, such as:
- "same behavior"
- "looks fixed"
- "working as expected"
Use explicit framing instead.
- `ai/context/index.md`
- `ai/context/workstreams/index.md`
- `ai/context/process/communication.md`
- `ai/context/people/index.md`