Browse Source
- Apply markdown.mdc formatting to all ruleset files (80-char line length, proper spacing) - Update timesafari.mdc to reflect completed migration (remove triple migration pattern references) - Clean up corrupted logging_standards.mdc and restore proper content - Streamline architectural_decision_record.mdc for better readability - Update all file dates to 2025-08-19 for consistency - Add proper document headers and metadata to all ruleset files - Remove duplicate content and improve file organization - Maintain alwaysApply settings and glob patterns appropriately Files affected: 15 ruleset files across app/, database/, development/, features/, workflow/ directoriesdidview-invalid-did-handling
Matthew Raymer
3 days ago
15 changed files with 1313 additions and 651 deletions
@ -1,316 +1,181 @@ |
|||
--- |
|||
description: |
|||
globs: |
|||
alwaysApply: true |
|||
--- |
|||
# Time Safari Context |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Core application context |
|||
|
|||
## Project Overview |
|||
|
|||
Time Safari is an application designed to foster community building through gifts, |
|||
gratitude, and collaborative projects. The app should make it extremely easy and |
|||
intuitive for users of any age and capability to recognize contributions, build |
|||
trust networks, and organize collective action. It is built on services that |
|||
preserve privacy and data sovereignty. |
|||
Time Safari is an application designed to foster community building through |
|||
gifts, gratitude, and collaborative projects. The app makes it easy and |
|||
intuitive for users of any age and capability to recognize contributions, |
|||
build trust networks, and organize collective action. It is built on services |
|||
that preserve privacy and data sovereignty. |
|||
|
|||
The ultimate goals of Time Safari are two-fold: |
|||
## Core Goals |
|||
|
|||
1. **Connect** Make it easy, rewarding, and non-threatening for people to |
|||
1. **Connect**: Make it easy, rewarding, and non-threatening for people to |
|||
connect with others who have similar interests, and to initiate activities |
|||
together. This helps people accomplish and learn from other individuals in |
|||
less-structured environments; moreover, it helps them discover who they want |
|||
to continue to support and with whom they want to maintain relationships. |
|||
together. |
|||
|
|||
2. **Reveal** Widely advertise the great support and rewards that are being |
|||
given and accepted freely, especially non-monetary ones. Using visuals and text, |
|||
display the kind of impact that gifts are making in the lives of others. Also |
|||
show useful and engaging reports of project statistics and personal accomplishments. |
|||
2. **Reveal**: Widely advertise the great support and rewards that are being |
|||
given and accepted freely, especially non-monetary ones, showing the impact |
|||
gifts make in people's lives. |
|||
|
|||
## Technical Foundation |
|||
|
|||
## Core Approaches |
|||
### Architecture |
|||
|
|||
Time Safari should help everyday users build meaningful connections and organize |
|||
collective efforts by: |
|||
- **Privacy-preserving claims architecture** via endorser.ch |
|||
- **Decentralized Identifiers (DIDs)**: User identities based on |
|||
public/private key pairs stored on devices |
|||
- **Cryptographic Verification**: All claims and confirmations are |
|||
cryptographically signed |
|||
- **User-Controlled Visibility**: Users explicitly control who can see their |
|||
identifiers and data |
|||
- **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron) |
|||
|
|||
1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts |
|||
and contributions people give to each other and their communities. |
|||
### Current Database State |
|||
|
|||
2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask |
|||
for or propose help on projects and interests that matter to them. |
|||
- **Database**: SQLite via Absurd SQL (browser) and native SQLite |
|||
(mobile/desktop) |
|||
- **Legacy Support**: IndexedDB (Dexie) for backward compatibility |
|||
- **Status**: Modern database architecture fully implemented |
|||
|
|||
3. **Building Trust Networks**: Enabling users to maintain their network and activity |
|||
visibility. Developing reputation through verified contributions and references, |
|||
which can be selectively shown to others outside the network. |
|||
### Core Technologies |
|||
|
|||
4. **Preserving Privacy**: Ensuring personal identifiers are only shared with |
|||
explicitly authorized contacts, allowing private individuals including children |
|||
to participate safely. |
|||
- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator |
|||
- **Styling**: TailwindCSS |
|||
- **Build**: Vite with platform-specific configs |
|||
- **Testing**: Playwright E2E, Jest unit tests |
|||
- **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy) |
|||
- **State**: Pinia stores |
|||
- **Platform Services**: Abstracted behind interfaces with factory pattern |
|||
|
|||
5. **Engaging Content**: Displaying people's records in compelling stories, and |
|||
highlighting those projects that are lifting people's lives long-term, both in |
|||
physical support and in emotional-spiritual-creative thriving. |
|||
## Development Principles |
|||
|
|||
### Code Organization |
|||
|
|||
## Technical Foundation |
|||
- **Platform Services**: Abstract platform-specific code behind interfaces |
|||
- **Service Factory**: Use `PlatformServiceFactory` for platform selection |
|||
- **Type Safety**: Strict TypeScript, no `any` types, use type guards |
|||
- **Modern Architecture**: Use current platform service patterns |
|||
|
|||
This application is built on a privacy-preserving claims architecture (via |
|||
endorser.ch) with these key characteristics: |
|||
### Architecture Patterns |
|||
|
|||
- **Decentralized Identifiers (DIDs)**: User identities are based on public/private |
|||
key pairs stored on their devices |
|||
- **Cryptographic Verification**: All claims and confirmations are |
|||
cryptographically signed |
|||
- **User-Controlled Visibility**: Users explicitly control who can see their |
|||
identifiers and data |
|||
- **Merkle-Chained Claims**: Claims are cryptographically chained for verification |
|||
and integrity |
|||
- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron |
|||
and CEFPython), and web browsers |
|||
- **Dependency Injection**: Services injected via mixins and factory pattern |
|||
- **Interface Segregation**: Small, focused interfaces over large ones |
|||
- **Composition over Inheritance**: Prefer mixins and composition |
|||
- **Single Responsibility**: Each component/service has one clear purpose |
|||
|
|||
## User Journey |
|||
### Testing Strategy |
|||
|
|||
The typical progression of usage follows these stages: |
|||
- **E2E**: Playwright for critical user journeys |
|||
- **Unit**: Jest with F.I.R.S.T. principles |
|||
- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI |
|||
- **Quality Assurance**: Comprehensive testing and validation |
|||
|
|||
1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude |
|||
for gifts received, building a foundation of acknowledgment. |
|||
## Current Development Focus |
|||
|
|||
2. **Project Proposals**: Users propose projects and ideas, reaching out to connect |
|||
with others who share similar interests. |
|||
### Active Development |
|||
|
|||
3. **Action Triggers**: Offers of help serve as triggers and motivations to execute |
|||
proposed projects, moving from ideas to action. |
|||
- **Feature Development**: Build new functionality using modern platform |
|||
services |
|||
- **Performance Optimization**: Improve app performance and user experience |
|||
- **Platform Enhancement**: Leverage platform-specific capabilities |
|||
- **Code Quality**: Maintain high standards and best practices |
|||
|
|||
## Context for LLM Development |
|||
### Development Metrics |
|||
|
|||
When developing new functionality for Time Safari, consider these design principles: |
|||
- **Code Quality**: High standards maintained across all platforms |
|||
- **Performance**: Optimized for all target devices |
|||
- **Testing**: Comprehensive coverage maintained |
|||
- **User Experience**: Focus on intuitive, accessible interfaces |
|||
|
|||
1. **Accessibility First**: Features should be usable by non-technical users with |
|||
minimal learning curve. |
|||
## Platform-Specific Considerations |
|||
|
|||
2. **Privacy by Design**: All features must respect user privacy and data sovereignty. |
|||
### Web (PWA) |
|||
|
|||
3. **Progressive Enhancement**: Core functionality should work across all devices, |
|||
with richer experiences where supported. |
|||
- **QR Scanning**: WebInlineQRScanner |
|||
- **Deep Linking**: URL parameters |
|||
- **File System**: Limited browser APIs |
|||
- **Build**: `npm run build:web` (development build) |
|||
|
|||
4. **Voluntary Collaboration**: The system should enable but never coerce participation. |
|||
### Mobile (Capacitor) |
|||
|
|||
5. **Trust Building**: Features should help build verifiable trust between users. |
|||
- **QR Scanning**: @capacitor-mlkit/barcode-scanning |
|||
- **Deep Linking**: App URL open events |
|||
- **File System**: Capacitor Filesystem |
|||
- **Build**: `npm run build:capacitor` |
|||
|
|||
6. **Network Effects**: Consider how features scale as more users join the platform. |
|||
### Desktop (Electron) |
|||
|
|||
7. **Low Resource Requirements**: The system should be lightweight enough to run |
|||
on inexpensive devices users already own. |
|||
- **File System**: Node.js fs |
|||
- **Build**: `npm run build:electron` |
|||
- **Distribution**: AppImage, DEB, DMG packages |
|||
|
|||
## Use Cases to Support |
|||
## Development Workflow |
|||
|
|||
### Build Commands |
|||
|
|||
```bash |
|||
# Web (development) |
|||
npm run build:web |
|||
|
|||
# Mobile |
|||
npm run build:capacitor |
|||
npm run build:native |
|||
|
|||
# Desktop |
|||
npm run build:electron |
|||
npm run build:electron:appimage |
|||
npm run build:electron:deb |
|||
npm run build:electron:dmg |
|||
``` |
|||
|
|||
### Testing Commands |
|||
|
|||
LLM development should focus on enhancing these key use cases: |
|||
```bash |
|||
# Web E2E |
|||
npm run test:web |
|||
|
|||
1. **Community Building**: Tools that help people find others with shared |
|||
interests and values. |
|||
# Mobile |
|||
npm run test:mobile |
|||
npm run test:android |
|||
npm run test:ios |
|||
|
|||
2. **Project Coordination**: Features that make it easy to propose collaborative |
|||
projects and to submit suggestions and offers to existing ones. |
|||
# Type checking |
|||
npm run type-check |
|||
npm run lint-fix |
|||
``` |
|||
|
|||
3. **Reputation Building**: Methods for users to showcase their contributions |
|||
and reliability, in contexts where they explicitly reveal that information. |
|||
## Key Constraints |
|||
|
|||
4. **Governance Experimentation**: Features that facilitate decision-making and |
|||
collective governance. |
|||
1. **Privacy First**: User identifiers remain private except when explicitly |
|||
shared |
|||
2. **Platform Compatibility**: Features must work across all target platforms |
|||
3. **Performance**: Must remain performant on older/simpler devices |
|||
4. **Modern Architecture**: New features should use current platform services |
|||
5. **Offline Capability**: Key functionality should work offline when feasible |
|||
|
|||
## Constraints |
|||
|
|||
When developing new features, be mindful of these constraints: |
|||
## Use Cases to Support |
|||
|
|||
1. **Community Building**: Tools for finding others with shared interests |
|||
2. **Project Coordination**: Easy proposal and collaboration on projects |
|||
3. **Reputation Building**: Showcasing contributions and reliability |
|||
4. **Governance**: Facilitating decision-making and collective governance |
|||
|
|||
## Resources |
|||
|
|||
- **Testing**: `docs/migration-testing/` |
|||
- **Architecture**: `docs/architecture-decisions.md` |
|||
- **Build Context**: `docs/build-modernization-context.md` |
|||
|
|||
--- |
|||
|
|||
1. **Privacy Preservation**: User identifiers must remain private except when |
|||
explicitly shared. |
|||
## Status: Active application context |
|||
|
|||
2. **Platform Limitations**: Features must work within the constraints of the target |
|||
app platforms, while aiming to leverage the best platform technology available. |
|||
|
|||
3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch |
|||
API capabilities. |
|||
|
|||
4. **Performance on Low-End Devices**: The application should remain performant |
|||
on older/simpler devices. |
|||
|
|||
5. **Offline-First When Possible**: Key functionality should work offline when feasible. |
|||
|
|||
## Project Technologies |
|||
|
|||
- Typescript using ES6 classes using vue-facing-decorator |
|||
- TailwindCSS |
|||
- Vite Build Tool |
|||
- Playwright E2E testing |
|||
- IndexDB |
|||
- Camera, Image uploads, QR Code reader, ... |
|||
|
|||
## Mobile Features |
|||
|
|||
- Deep Linking |
|||
- Local Notifications via a custom Capacitor plugin |
|||
|
|||
## Project Architecture |
|||
|
|||
- The application must work on web browser, PWA (Progressive Web Application), |
|||
desktop via Electron, and mobile via Capacitor |
|||
- Building for each platform is managed via Vite |
|||
|
|||
## Core Development Principles |
|||
|
|||
### DRY development |
|||
|
|||
- **Code Reuse** |
|||
- Extract common functionality into utility functions |
|||
- Create reusable components for UI patterns |
|||
- Implement service classes for shared business logic |
|||
- Use mixins for cross-cutting concerns |
|||
- Leverage TypeScript interfaces for shared type definitions |
|||
|
|||
- **Component Patterns** |
|||
- Create base components for common UI elements |
|||
- Implement higher-order components for shared behavior |
|||
- Use slot patterns for flexible component composition |
|||
- Create composable services for business logic |
|||
- Implement factory patterns for component creation |
|||
|
|||
- **State Management** |
|||
- Centralize state in Pinia stores |
|||
- Use computed properties for derived state |
|||
- Implement shared state selectors |
|||
- Create reusable state mutations |
|||
- Use action creators for common operations |
|||
|
|||
- **Error Handling** |
|||
- Implement centralized error handling |
|||
- Create reusable error components |
|||
- Use error boundary components |
|||
- Implement consistent error logging |
|||
- Create error type definitions |
|||
|
|||
- **Type Definitions** |
|||
- Create shared interfaces for common data structures |
|||
- Use type aliases for complex types |
|||
- Implement generic types for reusable components |
|||
- Create utility types for common patterns |
|||
- Use discriminated unions for state management |
|||
|
|||
- **API Integration** |
|||
- Create reusable API client classes |
|||
- Implement request/response interceptors |
|||
- Use consistent error handling patterns |
|||
- Create type-safe API endpoints |
|||
- Implement caching strategies |
|||
|
|||
- **Platform Services** |
|||
- Abstract platform-specific code behind interfaces |
|||
- Create platform-agnostic service layers |
|||
- Implement feature detection |
|||
- Use dependency injection for services |
|||
- Create service factories |
|||
|
|||
- **Testing** |
|||
- Create reusable test utilities |
|||
- Implement test factories |
|||
- Use shared test configurations |
|||
- Create reusable test helpers |
|||
- Implement consistent test patterns |
|||
- F.I.R.S.T. (for Unit Tests) |
|||
F – Fast |
|||
I – Independent |
|||
R – Repeatable |
|||
S – Self-validating |
|||
T – Timely |
|||
|
|||
### SOLID Principles |
|||
|
|||
- **Single Responsibility**: Each class/component should have only one reason to |
|||
change |
|||
- Components should focus on one specific feature (e.g., QR scanning, DID management) |
|||
- Services should handle one type of functionality (e.g., platform services, |
|||
crypto services) |
|||
- Utilities should provide focused helper functions |
|||
|
|||
- **Open/Closed**: Software entities should be open for extension but closed for |
|||
modification |
|||
- Use interfaces for service definitions |
|||
- Implement plugin architecture for platform-specific features |
|||
- Allow component behavior extension through props and events |
|||
|
|||
- **Liskov Substitution**: Objects should be replaceable with their subtypes |
|||
- Platform services should work consistently across web/mobile |
|||
- Authentication providers should be interchangeable |
|||
- Storage implementations should be swappable |
|||
|
|||
- **Interface Segregation**: Clients shouldn't depend on interfaces they don't use |
|||
- Break down large service interfaces into smaller, focused ones |
|||
- Component props should be minimal and purposeful |
|||
- Event emissions should be specific and targeted |
|||
|
|||
- **Dependency Inversion**: High-level modules shouldn't depend on low-level modules |
|||
- Use dependency injection for services |
|||
- Abstract platform-specific code behind interfaces |
|||
- Implement factory patterns for component creation |
|||
|
|||
### Law of Demeter |
|||
|
|||
- Components should only communicate with immediate dependencies |
|||
- Avoid chaining method calls (e.g., `this.service.getUser().getProfile().getName()`) |
|||
- Use mediator patterns for complex component interactions |
|||
- Implement facade patterns for subsystem access |
|||
- Keep component communication through defined events and props |
|||
|
|||
### Composition over Inheritance |
|||
|
|||
- Prefer building components through composition |
|||
- Use mixins for shared functionality |
|||
- Implement feature toggles through props |
|||
- Create higher-order components for common patterns |
|||
- Use service composition for complex features |
|||
|
|||
### Interface Segregation |
|||
|
|||
- Define clear interfaces for services |
|||
- Keep component APIs minimal and focused |
|||
- Split large interfaces into smaller, specific ones |
|||
- Use TypeScript interfaces for type definitions |
|||
- Implement role-based interfaces for different use cases |
|||
|
|||
### Fail Fast |
|||
|
|||
- Validate inputs early in the process |
|||
- Use TypeScript strict mode |
|||
- Implement comprehensive error handling |
|||
- Add runtime checks for critical operations |
|||
- Use assertions for development-time validation |
|||
|
|||
### Principle of Least Astonishment |
|||
|
|||
- Follow Vue.js conventions consistently |
|||
- Use familiar naming patterns |
|||
- Implement predictable component behaviors |
|||
- Maintain consistent error handling |
|||
- Keep UI interactions intuitive |
|||
|
|||
### Information Hiding |
|||
|
|||
- Encapsulate implementation details |
|||
- Use private class members |
|||
- Implement proper access modifiers |
|||
- Hide complex logic behind simple interfaces |
|||
- Use TypeScript's access modifiers effectively |
|||
|
|||
### Single Source of Truth |
|||
|
|||
- Use Pinia for state management |
|||
- Maintain one source for user data |
|||
- Centralize configuration management |
|||
- Use computed properties for derived state |
|||
- Implement proper state synchronization |
|||
|
|||
### Principle of Least Privilege |
|||
|
|||
- Implement proper access control |
|||
- Use minimal required permissions |
|||
- Follow privacy-by-design principles |
|||
- Restrict component access to necessary data |
|||
- Implement proper authentication/authorization |
|||
- **Priority**: Critical |
|||
- **Estimated Effort**: Ongoing reference |
|||
- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron |
|||
- **Stakeholders**: Development team, Product team |
|||
|
|||
@ -1,32 +1,61 @@ |
|||
--- |
|||
alwaysApply: true |
|||
description: when doing anything with capacitor assets |
|||
alwaysApply: false |
|||
--- |
|||
# Asset Configuration Directive |
|||
*Scope: Assets Only (icons, splashes, image pipelines) — not overall build orchestration* |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Asset management guidelines |
|||
|
|||
*Scope: Assets Only (icons, splashes, image pipelines) — not overall build |
|||
orchestration* |
|||
|
|||
## Intent |
|||
|
|||
- Version **asset configuration files** (optionally dev-time generated). |
|||
- **Do not** version platform asset outputs (Android/iOS/Electron); generate them **at build-time** with standard tools. |
|||
- **Do not** version platform asset outputs (Android/iOS/Electron); generate |
|||
them **at build-time** with standard tools. |
|||
- Keep existing per-platform build scripts unchanged. |
|||
|
|||
## Source of Truth |
|||
|
|||
- **Preferred (Capacitor default):** `resources/` as the single master source. |
|||
- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is explicitly configured to read from it. |
|||
- **Never** maintain both `resources/` and `assets/` as parallel sources. Migrate and delete the redundant folder. |
|||
- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is |
|||
explicitly configured to read from it. |
|||
- **Never** maintain both `resources/` and `assets/` as parallel sources. |
|||
Migrate and delete the redundant folder. |
|||
|
|||
## Config Files |
|||
|
|||
- Live under: `config/assets/` (committed). |
|||
- Examples: |
|||
- `config/assets/capacitor-assets.config.json` (or the path the tool expects) |
|||
- `config/assets/capacitor-assets.config.json` (or the path the tool |
|||
expects) |
|||
- `config/assets/android.assets.json` |
|||
- `config/assets/ios.assets.json` |
|||
- `config/assets/common.assets.yaml` (optional shared layer) |
|||
- **Dev-time generation allowed** for these configs; **build-time generation is forbidden**. |
|||
- **Dev-time generation allowed** for these configs; **build-time |
|||
generation is forbidden**. |
|||
|
|||
## Build-Time Behavior |
|||
|
|||
- Build generates platform assets (not configs) using the standard chain: |
|||
|
|||
```bash |
|||
npm run build:capacitor # web build via Vite (.mts) |
|||
npx cap sync |
|||
npx capacitor-assets generate # produces platform assets; not committed |
|||
# then platform-specific build steps |
|||
``` |
|||
|
|||
--- |
|||
|
|||
**Status**: Active asset management directive |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: capacitor-assets toolchain |
|||
**Stakeholders**: Development team, Build team |
|||
|
|||
npx capacitor-assets generate # produces platform assets; not committed |
|||
# then platform-specific build steps |
|||
|
|||
@ -1,76 +1,117 @@ |
|||
# Investigation Report Example |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Investigation methodology example |
|||
|
|||
## Investigation — Registration Dialog Test Flakiness |
|||
|
|||
## Objective |
|||
Identify root cause of flaky tests related to registration dialogs in contact import scenarios. |
|||
|
|||
Identify root cause of flaky tests related to registration dialogs in contact |
|||
import scenarios. |
|||
|
|||
## System Map |
|||
- User action → ContactInputForm → ContactsView.addContact() → handleRegistrationPrompt() |
|||
|
|||
- User action → ContactInputForm → ContactsView.addContact() → |
|||
handleRegistrationPrompt() |
|||
- setTimeout(1000ms) → Modal dialog → User response → Registration API call |
|||
- Test execution → Wait for dialog → Assert dialog content → Click response button |
|||
- Test execution → Wait for dialog → Assert dialog content → Click response |
|||
button |
|||
|
|||
## Findings (Evidence) |
|||
- **1-second timeout causes flakiness** — evidence: `src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in handleRegistrationPrompt() |
|||
- **Import flow bypasses dialogs** — evidence: `src/views/ContactImportView.vue:500-520`; importContacts() calls $insertContact() directly, no handleRegistrationPrompt() |
|||
- **Dialog only appears in direct add flow** — evidence: `src/views/ContactsView.vue:774-800`; addContact() calls handleRegistrationPrompt() after database insert |
|||
|
|||
- **1-second timeout causes flakiness** — evidence: |
|||
`src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in |
|||
handleRegistrationPrompt() |
|||
- **Import flow bypasses dialogs** — evidence: |
|||
`src/views/ContactImportView.vue:500-520`; importContacts() calls |
|||
$insertContact() directly, no handleRegistrationPrompt() |
|||
- **Dialog only appears in direct add flow** — evidence: |
|||
`src/views/ContactsView.vue:774-800`; addContact() calls |
|||
handleRegistrationPrompt() after database insert |
|||
|
|||
## Hypotheses & Failure Modes |
|||
- H1: 1-second timeout makes dialog appearance unpredictable; would fail when tests run faster than 1000ms |
|||
- H2: Test environment timing differs from development; watch for CI vs local test differences |
|||
|
|||
- H1: 1-second timeout makes dialog appearance unpredictable; would fail when |
|||
tests run faster than 1000ms |
|||
- H2: Test environment timing differs from development; watch for CI vs local |
|||
test differences |
|||
|
|||
## Corrections |
|||
- Updated: "Multiple dialogs interfere with imports" → "Import flow never triggers dialogs - they only appear in direct contact addition" |
|||
- Updated: "Complex batch registration needed" → "Simple timeout removal and test mode flag sufficient" |
|||
|
|||
- Updated: "Multiple dialogs interfere with imports" → "Import flow never |
|||
triggers dialogs - they only appear in direct contact addition" |
|||
- Updated: "Complex batch registration needed" → "Simple timeout removal and |
|||
test mode flag sufficient" |
|||
|
|||
## Diagnostics (Next Checks) |
|||
|
|||
- [ ] Repro on CI environment vs local |
|||
- [ ] Measure actual dialog appearance timing |
|||
- [ ] Test with setTimeout removed |
|||
- [ ] Verify import flow doesn't call handleRegistrationPrompt |
|||
|
|||
## Risks & Scope |
|||
- Impacted: Contact addition tests, registration workflow tests; Data: None; Users: Test suite reliability |
|||
|
|||
- Impacted: Contact addition tests, registration workflow tests; Data: None; |
|||
Users: Test suite reliability |
|||
|
|||
## Decision / Next Steps |
|||
|
|||
- Owner: Development Team; By: 2025-01-28 |
|||
- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests pass consistently |
|||
- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests |
|||
pass consistently |
|||
|
|||
## References |
|||
|
|||
- `src/views/ContactsView.vue:971-1000` |
|||
- `src/views/ContactImportView.vue:500-520` |
|||
- `src/views/ContactsView.vue:774-800` |
|||
|
|||
## Competence Hooks |
|||
- Why this works: Code path tracing revealed separate execution flows, evidence disproved initial assumptions |
|||
- Common pitfalls: Assuming related functionality without tracing execution paths, over-engineering solutions to imaginary problems |
|||
- Next skill: Learn to trace code execution before proposing architectural changes |
|||
- Teach-back: "What evidence shows that contact imports bypass registration dialogs?" |
|||
|
|||
--- |
|||
- Why this works: Code path tracing revealed separate execution flows, |
|||
evidence disproved initial assumptions |
|||
- Common pitfalls: Assuming related functionality without tracing execution |
|||
paths, over-engineering solutions to imaginary problems |
|||
- Next skill: Learn to trace code execution before proposing architectural |
|||
changes |
|||
- Teach-back: "What evidence shows that contact imports bypass registration |
|||
dialogs?" |
|||
|
|||
## Key Learning Points |
|||
|
|||
### Evidence-First Approach |
|||
|
|||
This investigation demonstrates the importance of: |
|||
|
|||
1. **Tracing actual code execution** rather than making assumptions |
|||
2. **Citing specific evidence** with file:line references |
|||
3. **Validating problem scope** before proposing solutions |
|||
4. **Considering simpler alternatives** before complex architectural changes |
|||
|
|||
### Code Path Tracing Value |
|||
|
|||
By tracing the execution paths, we discovered: |
|||
|
|||
- Import flow and direct add flow are completely separate |
|||
- The "multiple dialog interference" problem didn't exist |
|||
- A simple timeout removal would solve the actual issue |
|||
|
|||
### Prevention of Over-Engineering |
|||
|
|||
The investigation prevented: |
|||
|
|||
- Unnecessary database schema changes |
|||
- Complex batch registration systems |
|||
- Migration scripts for non-existent problems |
|||
- Architectural changes based on assumptions |
|||
description: |
|||
globs: |
|||
alwaysApply: false |
|||
|
|||
--- |
|||
|
|||
**Status**: Active investigation methodology |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: software_development.mdc |
|||
**Stakeholders**: Development team, QA team |
|||
|
|||
@ -0,0 +1,329 @@ |
|||
--- |
|||
alwaysApply: true |
|||
--- |
|||
# Time Handling in Development Workflow |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-17 |
|||
**Status**: 🎯 **ACTIVE** - Production Ready |
|||
|
|||
## Overview |
|||
|
|||
This guide establishes **how time should be referenced and used** across the |
|||
development workflow. It is not tied to any one project, but applies to **all |
|||
feature development, issue investigations, ADRs, and documentation**. |
|||
|
|||
## General Principles |
|||
|
|||
- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over |
|||
relative references like "last week." |
|||
- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in |
|||
docs, issues, ADRs, and commits. |
|||
- **Time zones**: Default to **UTC** unless explicitly tied to user-facing |
|||
behavior. |
|||
- **Precision**: Only specify as much precision as needed (date vs. datetime vs. |
|||
timestamp). |
|||
- **Consistency**: Align time references across ADRs, commits, and investigation |
|||
reports. |
|||
|
|||
## In Documentation & ADRs |
|||
|
|||
- Record decision dates using **absolute ISO dates**. |
|||
- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` → |
|||
`2025-08-17`). |
|||
- Avoid ambiguous terms like *recently*, *last month*, or *soon*. |
|||
- For time-based experiments (e.g., A/B tests), always include: |
|||
|
|||
- Start date |
|||
- Expected duration |
|||
- Review date checkpoint |
|||
|
|||
## In Code & Commits |
|||
|
|||
- Use **UTC timestamps** in logs, DB migrations, and serialized formats. |
|||
- In commits, link changes to **date-bound ADRs or investigation docs**. |
|||
- For migrations, include both **applied date** and **intended version window**. |
|||
- Use constants for known fixed dates; avoid hardcoding arbitrary strings. |
|||
|
|||
## In Investigations & Research |
|||
|
|||
- Capture **when** an issue occurred (absolute time or version tag). |
|||
- When describing failures: note whether they are **time-sensitive** (e.g., after |
|||
migrations, cache expirations). |
|||
- Record diagnostic timelines in ISO format (not relative). |
|||
- For performance regressions, annotate both **baseline timeframe** and |
|||
**measurement timeframe**. |
|||
|
|||
## Collaboration Hooks |
|||
|
|||
- During reviews, verify **time references are clear, absolute, and |
|||
standardized**. |
|||
- In syncs, reframe relative terms ("this week") into shared absolute |
|||
references. |
|||
- Tag ADRs with both **date created** and **review by** checkpoints. |
|||
|
|||
## Self-Check Before Submitting |
|||
|
|||
- [ ] Did I check the time using the **developer's actual system time and |
|||
timezone**? |
|||
- [ ] Am I using absolute ISO dates? |
|||
- [ ] Is UTC assumed unless specified otherwise? |
|||
- [ ] Did I avoid ambiguous relative terms? |
|||
- [ ] If duration matters, did I specify both start and end? |
|||
- [ ] For future work, did I include a review/revisit date? |
|||
|
|||
## Real-Time Context in Developer Interactions |
|||
|
|||
- The model must always resolve **"current time"** using the **developer's |
|||
actual system time and timezone**. |
|||
- When generating timestamps (e.g., in investigation logs, ADRs, or examples), |
|||
the model should: |
|||
|
|||
- Use the **developer's current local time** by default. |
|||
- Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`). |
|||
- Optionally provide UTC alongside if context requires cross-team clarity. |
|||
|
|||
- When interpreting relative terms like *now*, *today*, *last week*: |
|||
|
|||
- Resolve them against the **developer's current time**. |
|||
- Convert them into **absolute ISO-8601 values** in the output. |
|||
|
|||
## LLM Time Checking Instructions |
|||
|
|||
**CRITICAL**: The LLM must actively query the system for current time rather |
|||
than assuming or inventing times. |
|||
|
|||
### How to Check Current Time |
|||
|
|||
#### 1. **Query System Time (Required)** |
|||
|
|||
- **Always start** by querying the current system time using available tools |
|||
- **Never assume** what the current time is |
|||
- **Never use** placeholder values like "current time" or "now" |
|||
|
|||
#### 2. **Available Time Query Methods** |
|||
|
|||
- **System Clock**: Use `date` command or equivalent system time function |
|||
- **Programming Language**: Use language-specific time functions (e.g., |
|||
`Date.now()`, `datetime.now()`) |
|||
- **Environment Variables**: Check for time-related environment variables |
|||
- **API Calls**: Use time service APIs if available |
|||
|
|||
#### 3. **Required Time Information** |
|||
|
|||
When querying time, always obtain: |
|||
|
|||
- **Current Date**: YYYY-MM-DD format |
|||
- **Current Time**: HH:MM:SS format (24-hour) |
|||
- **Timezone**: Current system timezone or UTC offset |
|||
- **UTC Equivalent**: Convert local time to UTC for cross-team clarity |
|||
|
|||
#### 4. **Time Query Examples** |
|||
|
|||
```bash |
|||
# Example: Query system time |
|||
$ date |
|||
# Expected output: Mon Aug 17 10:32:45 EDT 2025 |
|||
|
|||
# Example: Query UTC time |
|||
$ date -u |
|||
# Expected output: Mon Aug 17 14:32:45 UTC 2025 |
|||
``` |
|||
|
|||
```python |
|||
# Example: Python time query |
|||
import datetime |
|||
current_time = datetime.datetime.now() |
|||
utc_time = datetime.datetime.utcnow() |
|||
print(f"Local: {current_time}") |
|||
print(f"UTC: {utc_time}") |
|||
``` |
|||
|
|||
```javascript |
|||
// Example: JavaScript time query |
|||
const now = new Date(); |
|||
const utc = new Date().toISOString(); |
|||
console.log(`Local: ${now}`); |
|||
console.log(`UTC: ${utc}`); |
|||
``` |
|||
|
|||
#### 5. **LLM Time Checking Workflow** |
|||
|
|||
1. **Query**: Actively query system for current time |
|||
2. **Validate**: Confirm time data is reasonable and current |
|||
3. **Format**: Convert to ISO 8601 format |
|||
4. **Context**: Provide both local and UTC times when helpful |
|||
5. **Document**: Show the source of time information |
|||
|
|||
#### 6. **Error Handling for Time Queries** |
|||
|
|||
- **If time query fails**: Ask user for current time or use "unknown time" |
|||
with explanation |
|||
- **If timezone unclear**: Default to UTC and ask for clarification |
|||
- **If time seems wrong**: Verify with user before proceeding |
|||
- **Always log**: Record when and how time was obtained |
|||
|
|||
#### 7. **Time Query Verification** |
|||
|
|||
Before using queried time, verify: |
|||
|
|||
- [ ] Time is recent (within last few minutes) |
|||
- [ ] Timezone information is available |
|||
- [ ] UTC conversion is accurate |
|||
- [ ] Format follows ISO 8601 standard |
|||
|
|||
## Model Behavior Rules |
|||
|
|||
- **Never invent a "fake now"**: All "current time" references must come from |
|||
the real system clock available at runtime. |
|||
- **Check developer time zone**: If ambiguous, ask for clarification (e.g., |
|||
"Should I use UTC or your local timezone?"). |
|||
- **Format for clarity**: |
|||
|
|||
- Local time: `YYYY-MM-DDTHH:mm±hh:mm` |
|||
- UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ` |
|||
|
|||
## Examples |
|||
|
|||
### Good |
|||
|
|||
- "Feature flag rollout started on `2025-08-01` and will be reviewed on |
|||
`2025-08-21`." |
|||
- "Migration applied on `2025-07-15T14:00Z`." |
|||
- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` / |
|||
`2025-08-17T14:00Z (UTC)`." |
|||
|
|||
### Bad |
|||
|
|||
- "Feature flag rolled out last week." |
|||
- "Migration applied recently." |
|||
- "Now is August, so we assume this was last month." |
|||
|
|||
### More Examples |
|||
|
|||
#### Issue Reports |
|||
|
|||
- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue |
|||
persisted until `2025-08-17T15:45:00Z`." |
|||
- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a |
|||
while." |
|||
|
|||
#### Release Planning |
|||
|
|||
- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing |
|||
window: `2025-08-20` to `2025-08-24`." |
|||
- ❌ **Bad**: "Feature X will be released next week after testing." |
|||
|
|||
#### Performance Monitoring |
|||
|
|||
- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`. |
|||
Regression detected on `2025-08-15T14:00:00Z`." |
|||
- ❌ **Bad**: "Performance was good last week but got worse this week." |
|||
|
|||
## Technical Implementation Notes |
|||
|
|||
### UTC Storage Principle |
|||
|
|||
- **Store all timestamps in UTC** in databases, logs, and serialized formats |
|||
- **Convert to local time only for user display** |
|||
- **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ` |
|||
|
|||
### Common Implementation Patterns |
|||
|
|||
#### Database Storage |
|||
|
|||
```sql |
|||
-- ✅ Good: Store in UTC |
|||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
|||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
|||
|
|||
-- ❌ Bad: Store in local time |
|||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
|||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
|||
``` |
|||
|
|||
#### API Responses |
|||
|
|||
```json |
|||
// ✅ Good: Include both UTC and local time |
|||
{ |
|||
"eventTime": "2025-08-17T14:00:00Z", |
|||
"localTime": "2025-08-17T10:00:00-04:00", |
|||
"timezone": "America/New_York" |
|||
} |
|||
|
|||
// ❌ Bad: Only local time |
|||
{ |
|||
"eventTime": "2025-08-17T10:00:00-04:00" |
|||
} |
|||
``` |
|||
|
|||
#### Logging |
|||
|
|||
```python |
|||
# ✅ Good: Log in UTC with timezone info |
|||
logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") |
|||
|
|||
# ❌ Bad: Log in local time |
|||
logger.info(f"User action at {datetime.now()}") |
|||
``` |
|||
|
|||
### Timezone Handling Best Practices |
|||
|
|||
#### 1. Always Store Timezone Information |
|||
|
|||
- Include IANA timezone identifier (e.g., `America/New_York`) |
|||
- Store UTC offset at time of creation |
|||
- Handle daylight saving time transitions automatically |
|||
|
|||
#### 2. User Display Considerations |
|||
|
|||
- Convert UTC to user's preferred timezone |
|||
- Show timezone abbreviation when helpful |
|||
- Use relative time for recent events ("2 hours ago") |
|||
|
|||
#### 3. Edge Case Handling |
|||
|
|||
- **Daylight Saving Time**: Use timezone-aware libraries |
|||
- **Leap Seconds**: Handle gracefully (rare but important) |
|||
- **Invalid Times**: Validate before processing |
|||
|
|||
### Common Mistakes to Avoid |
|||
|
|||
#### 1. Timezone Confusion |
|||
|
|||
- ❌ **Don't**: Assume server timezone is user timezone |
|||
- ✅ **Do**: Always convert UTC to user's local time for display |
|||
|
|||
#### 2. Format Inconsistency |
|||
|
|||
- ❌ **Don't**: Mix different time formats in the same system |
|||
- ✅ **Do**: Standardize on ISO 8601 for all storage |
|||
|
|||
#### 3. Relative Time References |
|||
|
|||
- ❌ **Don't**: Use relative terms in persistent storage |
|||
- ✅ **Do**: Convert relative terms to absolute timestamps immediately |
|||
|
|||
## References |
|||
|
|||
- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601) |
|||
- [IANA Timezone Database](https://www.iana.org/time-zones) |
|||
- [ADR Template](./adr_template.md) |
|||
- [Research & Diagnostic Workflow](./research_diagnostic.mdc) |
|||
|
|||
--- |
|||
|
|||
**Rule of Thumb**: Every time reference in development artifacts should be |
|||
**clear in 6 months without context**, and aligned to the **developer's actual |
|||
current time**. |
|||
|
|||
**Technical Rule of Thumb**: **Store in UTC, display in local time, always |
|||
include timezone context.** |
|||
|
|||
--- |
|||
|
|||
**Status**: Active |
|||
**Version**: 1.0 |
|||
**Maintainer**: Matthew Raymer |
|||
**Next Review**: 2025-09-17 |
|||
Loading…
Reference in new issue