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 |
# Time Safari Context |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-19 |
||||
|
**Status**: 🎯 **ACTIVE** - Core application context |
||||
|
|
||||
## Project Overview |
## Project Overview |
||||
|
|
||||
Time Safari is an application designed to foster community building through gifts, |
Time Safari is an application designed to foster community building through |
||||
gratitude, and collaborative projects. The app should make it extremely easy and |
gifts, gratitude, and collaborative projects. The app makes it easy and |
||||
intuitive for users of any age and capability to recognize contributions, build |
intuitive for users of any age and capability to recognize contributions, |
||||
trust networks, and organize collective action. It is built on services that |
build trust networks, and organize collective action. It is built on services |
||||
preserve privacy and data sovereignty. |
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 |
connect with others who have similar interests, and to initiate activities |
||||
together. This helps people accomplish and learn from other individuals in |
together. |
||||
less-structured environments; moreover, it helps them discover who they want |
|
||||
to continue to support and with whom they want to maintain relationships. |
|
||||
|
|
||||
2. **Reveal** Widely advertise the great support and rewards that are being |
2. **Reveal**: Widely advertise the great support and rewards that are being |
||||
given and accepted freely, especially non-monetary ones. Using visuals and text, |
given and accepted freely, especially non-monetary ones, showing the impact |
||||
display the kind of impact that gifts are making in the lives of others. Also |
gifts make in people's lives. |
||||
show useful and engaging reports of project statistics and personal accomplishments. |
|
||||
|
|
||||
|
## Technical Foundation |
||||
|
|
||||
## Core Approaches |
### Architecture |
||||
|
|
||||
Time Safari should help everyday users build meaningful connections and organize |
- **Privacy-preserving claims architecture** via endorser.ch |
||||
collective efforts by: |
- **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 |
### Current Database State |
||||
and contributions people give to each other and their communities. |
|
||||
|
|
||||
2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask |
- **Database**: SQLite via Absurd SQL (browser) and native SQLite |
||||
for or propose help on projects and interests that matter to them. |
(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 |
### Core Technologies |
||||
visibility. Developing reputation through verified contributions and references, |
|
||||
which can be selectively shown to others outside the network. |
|
||||
|
|
||||
4. **Preserving Privacy**: Ensuring personal identifiers are only shared with |
- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator |
||||
explicitly authorized contacts, allowing private individuals including children |
- **Styling**: TailwindCSS |
||||
to participate safely. |
- **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 |
## Development Principles |
||||
highlighting those projects that are lifting people's lives long-term, both in |
|
||||
physical support and in emotional-spiritual-creative thriving. |
|
||||
|
|
||||
|
### 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 |
### Architecture Patterns |
||||
endorser.ch) with these key characteristics: |
|
||||
|
|
||||
- **Decentralized Identifiers (DIDs)**: User identities are based on public/private |
- **Dependency Injection**: Services injected via mixins and factory pattern |
||||
key pairs stored on their devices |
- **Interface Segregation**: Small, focused interfaces over large ones |
||||
- **Cryptographic Verification**: All claims and confirmations are |
- **Composition over Inheritance**: Prefer mixins and composition |
||||
cryptographically signed |
- **Single Responsibility**: Each component/service has one clear purpose |
||||
- **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 |
|
||||
|
|
||||
## 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 |
## Current Development Focus |
||||
for gifts received, building a foundation of acknowledgment. |
|
||||
|
|
||||
2. **Project Proposals**: Users propose projects and ideas, reaching out to connect |
### Active Development |
||||
with others who share similar interests. |
|
||||
|
|
||||
3. **Action Triggers**: Offers of help serve as triggers and motivations to execute |
- **Feature Development**: Build new functionality using modern platform |
||||
proposed projects, moving from ideas to action. |
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 |
## Platform-Specific Considerations |
||||
minimal learning curve. |
|
||||
|
|
||||
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, |
- **QR Scanning**: WebInlineQRScanner |
||||
with richer experiences where supported. |
- **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 |
- **File System**: Node.js fs |
||||
on inexpensive devices users already own. |
- **Build**: `npm run build:electron` |
||||
|
- **Distribution**: AppImage, DEB, DMG packages |
||||
|
|
||||
## Use Cases to Support |
## Development Workflow |
||||
|
|
||||
|
### Build Commands |
||||
|
|
||||
LLM development should focus on enhancing these key use cases: |
```bash |
||||
|
# Web (development) |
||||
|
npm run build:web |
||||
|
|
||||
1. **Community Building**: Tools that help people find others with shared |
# Mobile |
||||
interests and values. |
npm run build:capacitor |
||||
|
npm run build:native |
||||
|
|
||||
2. **Project Coordination**: Features that make it easy to propose collaborative |
# Desktop |
||||
projects and to submit suggestions and offers to existing ones. |
npm run build:electron |
||||
|
npm run build:electron:appimage |
||||
|
npm run build:electron:deb |
||||
|
npm run build:electron:dmg |
||||
|
``` |
||||
|
|
||||
3. **Reputation Building**: Methods for users to showcase their contributions |
### Testing Commands |
||||
and reliability, in contexts where they explicitly reveal that information. |
|
||||
|
|
||||
4. **Governance Experimentation**: Features that facilitate decision-making and |
```bash |
||||
collective governance. |
# Web E2E |
||||
|
npm run test:web |
||||
|
|
||||
## Constraints |
# Mobile |
||||
|
npm run test:mobile |
||||
When developing new features, be mindful of these constraints: |
npm run test:android |
||||
|
npm run test:ios |
||||
|
|
||||
|
# Type checking |
||||
|
npm run type-check |
||||
|
npm run lint-fix |
||||
|
``` |
||||
|
|
||||
|
## Key Constraints |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
## 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 |
## Status: Active application context |
||||
explicitly shared. |
|
||||
|
|
||||
2. **Platform Limitations**: Features must work within the constraints of the target |
- **Priority**: Critical |
||||
app platforms, while aiming to leverage the best platform technology available. |
- **Estimated Effort**: Ongoing reference |
||||
|
- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron |
||||
3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch |
- **Stakeholders**: Development team, Product team |
||||
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 |
|
||||
|
|||||
@ -1,32 +1,61 @@ |
|||||
--- |
--- |
||||
alwaysApply: true |
description: when doing anything with capacitor assets |
||||
|
alwaysApply: false |
||||
--- |
--- |
||||
# Asset Configuration Directive |
# 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 |
## Intent |
||||
|
|
||||
- Version **asset configuration files** (optionally dev-time generated). |
- 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. |
- Keep existing per-platform build scripts unchanged. |
||||
|
|
||||
## Source of Truth |
## Source of Truth |
||||
|
|
||||
- **Preferred (Capacitor default):** `resources/` as the single master source. |
- **Preferred (Capacitor default):** `resources/` as the single master source. |
||||
- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is explicitly configured to read from it. |
- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is |
||||
- **Never** maintain both `resources/` and `assets/` as parallel sources. Migrate and delete the redundant folder. |
explicitly configured to read from it. |
||||
|
- **Never** maintain both `resources/` and `assets/` as parallel sources. |
||||
|
Migrate and delete the redundant folder. |
||||
|
|
||||
## Config Files |
## Config Files |
||||
|
|
||||
- Live under: `config/assets/` (committed). |
- Live under: `config/assets/` (committed). |
||||
- Examples: |
- 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/android.assets.json` |
||||
- `config/assets/ios.assets.json` |
- `config/assets/ios.assets.json` |
||||
- `config/assets/common.assets.yaml` (optional shared layer) |
- `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-Time Behavior |
||||
|
|
||||
- Build generates platform assets (not configs) using the standard chain: |
- Build generates platform assets (not configs) using the standard chain: |
||||
```bash |
|
||||
npm run build:capacitor # web build via Vite (.mts) |
```bash |
||||
npx cap sync |
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 |
npx capacitor-assets generate # produces platform assets; not committed |
||||
# then platform-specific build steps |
# then platform-specific build steps |
||||
|
|||||
@ -1,76 +1,117 @@ |
|||||
# Investigation Report Example |
# Investigation Report Example |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-19 |
||||
|
**Status**: 🎯 **ACTIVE** - Investigation methodology example |
||||
|
|
||||
## Investigation — Registration Dialog Test Flakiness |
## Investigation — Registration Dialog Test Flakiness |
||||
|
|
||||
## Objective |
## 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 |
## System Map |
||||
- User action → ContactInputForm → ContactsView.addContact() → handleRegistrationPrompt() |
|
||||
|
- User action → ContactInputForm → ContactsView.addContact() → |
||||
|
handleRegistrationPrompt() |
||||
- setTimeout(1000ms) → Modal dialog → User response → Registration API call |
- 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) |
## 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() |
- **1-second timeout causes flakiness** — evidence: |
||||
- **Dialog only appears in direct add flow** — evidence: `src/views/ContactsView.vue:774-800`; addContact() calls handleRegistrationPrompt() after database insert |
`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 |
## 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 |
## 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) |
## Diagnostics (Next Checks) |
||||
|
|
||||
- [ ] Repro on CI environment vs local |
- [ ] Repro on CI environment vs local |
||||
- [ ] Measure actual dialog appearance timing |
- [ ] Measure actual dialog appearance timing |
||||
- [ ] Test with setTimeout removed |
- [ ] Test with setTimeout removed |
||||
- [ ] Verify import flow doesn't call handleRegistrationPrompt |
- [ ] Verify import flow doesn't call handleRegistrationPrompt |
||||
|
|
||||
## Risks & Scope |
## 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 |
## Decision / Next Steps |
||||
|
|
||||
- Owner: Development Team; By: 2025-01-28 |
- 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 |
## References |
||||
|
|
||||
- `src/views/ContactsView.vue:971-1000` |
- `src/views/ContactsView.vue:971-1000` |
||||
- `src/views/ContactImportView.vue:500-520` |
- `src/views/ContactImportView.vue:500-520` |
||||
- `src/views/ContactsView.vue:774-800` |
- `src/views/ContactsView.vue:774-800` |
||||
|
|
||||
## Competence Hooks |
## 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 |
## Key Learning Points |
||||
|
|
||||
### Evidence-First Approach |
### Evidence-First Approach |
||||
|
|
||||
This investigation demonstrates the importance of: |
This investigation demonstrates the importance of: |
||||
|
|
||||
1. **Tracing actual code execution** rather than making assumptions |
1. **Tracing actual code execution** rather than making assumptions |
||||
2. **Citing specific evidence** with file:line references |
2. **Citing specific evidence** with file:line references |
||||
3. **Validating problem scope** before proposing solutions |
3. **Validating problem scope** before proposing solutions |
||||
4. **Considering simpler alternatives** before complex architectural changes |
4. **Considering simpler alternatives** before complex architectural changes |
||||
|
|
||||
### Code Path Tracing Value |
### Code Path Tracing Value |
||||
|
|
||||
By tracing the execution paths, we discovered: |
By tracing the execution paths, we discovered: |
||||
|
|
||||
- Import flow and direct add flow are completely separate |
- Import flow and direct add flow are completely separate |
||||
- The "multiple dialog interference" problem didn't exist |
- The "multiple dialog interference" problem didn't exist |
||||
- A simple timeout removal would solve the actual issue |
- A simple timeout removal would solve the actual issue |
||||
|
|
||||
### Prevention of Over-Engineering |
### Prevention of Over-Engineering |
||||
|
|
||||
The investigation prevented: |
The investigation prevented: |
||||
|
|
||||
- Unnecessary database schema changes |
- Unnecessary database schema changes |
||||
- Complex batch registration systems |
- Complex batch registration systems |
||||
- Migration scripts for non-existent problems |
- Migration scripts for non-existent problems |
||||
- Architectural changes based on assumptions |
- 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