maintain-tech-details

name	maintain-tech-details
description	Maintain tech-details.md as the implementation source of truth for a project. Use when Codex needs to create, update, audit, refactor, or reason about tech-details.md; align technical facts with project-state.md, plan.md, and idea.md; separate implementation details from product intent, roadmap status, and project memory.

maintain-tech-details

Maintain tech-details.md as the implementation source of truth for the project.

This file should describe how the project is technically built, not what the product is conceptually, and not the current task status.

Editing Behavior

For initial creation:

• Before creating a new tech-details.md, ask the user whether Phase 1 and Phase 2 discovery must be run first. Do not create the file until the user answers, unless they already explicitly told you to run or skip those phases.
• If the user says to run the phases, run Phase 1 and Phase 2 discovery before writing.
• If the user says to skip the phases, create the file only from confirmed repository facts and user-provided details, and put unresolved decisions in ## Open Technical Questions.
• Populate only sections where technical decisions have been confirmed through discovery or existing files.
• If the user asks to make an initial project structure, create or update the ## Project Structure section in tech-details.md; do not scaffold files or directories.
• Leave unconfirmed sections as empty headings or omit them entirely.
• Do not invent details to fill gaps; add them to ## Open Technical Questions.

For small changes:

• Update only the relevant section.
• Keep surrounding content unchanged.

For larger changes:

• Reorganize only if it improves clarity.
• Preserve useful existing content.
• Summarize major changes after editing.

For audits:

• Identify contradictions.
• Identify missing technical decisions.
• Identify content that belongs in another file.
• Suggest exact edits.

Output Format

When responding to the user:

1. Briefly state what changed or what should change.
2. Mention any assumptions.
3. Mention any items that should move to idea.md, plan.md, or project-state.md.
4. Do not paste the full file unless the user asks for it.

Project Rules

• project-state.md is the first file to read.
• tech-details.md is the implementation truth.
• plan.md is the task status truth.
• idea.md is the product intent truth.
• Do not invent architecture; propose first.
• Before creating tech-details.md, explicitly ask whether Phase 1 and Phase 2 discovery must be run first.
• Run discovery phases before writing when creating or significantly updating tech-details.md, except when the user explicitly says to skip them for initial creation.
• The checklist is a guideline; determine applicability through Phase 1 before documenting anything.

Checklist as Guideline

The following categories are a guideline for what tech-details.md may need to cover - not a rigid template. Not every item applies to every project. The discovery process below determines which items are in scope.

Stack

• Tech stack
• Cost estimation (hosting, services, third-party APIs)

Design - UI/UX

• Design inspiration and references
• Wireframes, mockups, or prototypes
• Style guides and design systems
• Copywriting and content gathering
• Asset gathering (icons, images, fonts, logos)
• Responsiveness and accessibility (WCAG)

Design - System Architecture

• Folder/project structure and modularity
• DB schema
• API design and documentation
• API versioning strategy
• Infrastructure (servers, cloud, CDN, CI/CD)
• Security
• Scalability and performance
• Third-party integrations

Environment Setup

• Version control
• Git branching strategy and commit conventions
• Pre-commit hooks (Husky, lint-staged, or equivalent)
• CI/CD pipelines
• Local and staging environments
• Secrets management
• Package managers
• Build tools
• Linters and formatters (tools, config files, integration points)
• .editorconfig
• Testing frameworks
• Initial documentation and README

Development - Backend

• API endpoints
• Database and ORM integration
• Seed and fixture data for dev and staging
• Authentication
• Data validation
• Security
• Rate limiting and throttling
• File uploads and storage
• Email and transactional notifications
• Error handling and logging
• Background jobs
• Caching
• Unit and integration tests

Development - Frontend

• Routing and component structure
• UI components and layouts
• Error states, empty states, and fallback UI (404, 500, skeletons)
• Toast and notification system
• State management
• API integration
• Form validation and error handling
• Responsiveness and accessibility
• Asset optimization (images, fonts, lazy loading, WebP)
• Favicon and app icons
• Unit tests
• SEO (meta tags, Open Graph, Twitter cards, sitemap.xml, robots.txt, structured data)
• Analytics

Integration & Testing

• Frontend and backend integration
• Integration and end-to-end testing
• Performance testing
• Load and stress testing
• Security testing
• Cross-browser and device testing
• Accessibility audits

Legal & Compliance

• Privacy Policy
• Terms of Service
• Cookie consent and banner
• GDPR/CCPA compliance
• License

Deployment

• Production infrastructure
• Database migrations
• CI/CD for production
• Environment variables in production
• Domain, HTTPS (SSL/TLS), and DNS
• CDN setup
• Monitoring, logging, and alerting
• Backups and recovery plans
• Rollback plan and strategy
• Post-deployment smoke tests
• Maintenance and support plan

Project Context

For project-related requests in an existing workspace, read project-state.md first when it exists. Treat the workspace files as the source of truth, including workspace-local skills; installed copies under .codex are runtime copies, not canonical project state.

Read Order

Before changing tech-details.md, read:

1. project-state.md
2. tech-details.md
3. plan.md if task status, phases, or priorities are relevant
4. idea.md only if product intent or MVP scope is needed

If creating tech-details.md for the first time, read whatever exists and note which files are missing. Before writing the new file, ask whether Phase 1 and Phase 2 discovery must be run first, unless the user already explicitly answered that. Do not block on missing files; if the user skips discovery, capture only what is technically known so far and put unknowns in ## Open Technical Questions.

Discovery Process

When creating tech-details.md, first ask whether Phase 1 and Phase 2 discovery must be run before the file is created. Do not create the file until the user answers, unless the user already explicitly instructed you to run or skip discovery.

When the user says to run discovery, or when making a significant update to an existing tech-details.md, run two rounds of structured questioning before writing. Do not invent or assume details; surface them through questions. If project files already answer some questions, skip those and only ask about the unknowns.

Ask all questions within a phase together as a single grouped message. Do not ask one question at a time. Wait for responses before proceeding to the next phase.

---

Phase 1 - Scoping: Which Checklist Items Apply?

The goal is to determine which checklist categories and items are in scope for this project. Ask all of the following questions at once, grouped by category:

Stack & Cost

• What is the primary language and runtime?
• Is there a framework already chosen or in use?
• Are there any third-party APIs or paid services involved?
• Is cost estimation needed (cloud hosting, SaaS tools, metered API usage)?

UI/UX

• Does this project have a user-facing frontend?
• Is there an existing design (Figma, mockups, style guide, or design system)?
• Are there specific accessibility requirements (e.g., WCAG 2.1 AA)?
• Are branding assets already gathered (logo, fonts, icons)?

System Architecture

• Is there an existing database, or is one being designed from scratch?
• Does the project expose an API, consume one, or both?
• Are there known scalability or performance constraints?
• Are there third-party service integrations planned?

Environment Setup

• Is there an existing repo with tooling already configured, or is this greenfield?
• Is there a defined branching strategy or commit convention?
• Are pre-commit hooks needed or already configured?
• Is CI/CD already set up or planned?
• How are secrets managed (e.g., .env files, Vault, cloud secrets manager)?

Backend

• Is there a backend? What kind (REST, GraphQL, serverless, monolith)?
• Is authentication required? What kind (session, JWT, OAuth, SSO)?
• Are file upload or storage features needed?
• Are background jobs, queues, or scheduled tasks needed?
• Are rate limiting, caching, or email/notification features needed?

Frontend

• Is there a frontend framework in use or decided?
• Is state management needed? Is there a preferred approach?
• Are there SEO requirements (public-facing pages, Open Graph, sitemaps)?
• Is analytics or event tracking needed?
• Are there specific performance targets (Lighthouse scores, Core Web Vitals)?

Testing & Integration

• What kinds of testing are expected (unit, integration, E2E, performance, load, security)?
• Is there a minimum coverage requirement?
• Are cross-browser or cross-device requirements defined?
• Are accessibility audits planned?

Legal & Compliance

• Is this project user-facing and public?
• Are there privacy regulations to comply with (GDPR, CCPA)?
• Is a license needed for the codebase?
• Are cookie consent, a privacy policy, or terms of service required?

Deployment

• Where will this be deployed (cloud provider, PaaS, bare metal, edge)?
• Is a CDN required?
• What are the monitoring, logging, and alerting expectations?
• Is a rollback strategy, backup plan, or disaster recovery plan needed?
• Is there a post-launch maintenance or support plan?

---

After receiving Phase 1 responses, compile the confirmed scope. Label each item:

• In scope - confirmed applicable
• Out of scope - explicitly not needed for this project
• Open question - not yet determined

Only proceed to Phase 2 for in-scope items.

---

Phase 2 - Detail Extraction: What Are the Specifics?

For each confirmed in-scope item, ask follow-up questions to gather enough detail to document it accurately. Ask all questions for a given category together. Skip out-of-scope categories entirely.

Stack

• What exact versions are targeted or in use?
• What is the package manager and where is the runtime version pinned (.nvmrc, .node-version, pyproject.toml, packageManager field, Docker base image)?
• What are the build tools and their config file names?

Cost Estimation

• What are the expected hosting tiers or instance sizes?
• Which third-party APIs have metered costs, and what are the expected usage volumes?
• Are there budget constraints or cost ceilings to document?

UI/UX & Design System

• What design tool is used (Figma, Sketch, Adobe XD)?
• Is there a component library (Tailwind, shadcn/ui, MUI, Radix, custom)?
• What is the typography system and color palette?
• Where are assets stored and how are they delivered to the app?
• What WCAG conformance level is targeted?

System Architecture

• What are the major modules or services and their ownership boundaries?
• What are the primary data entities and their key relationships?
• How is the API versioned (URL prefix, header, none)?
• What cloud provider and specific services are used (compute, managed DB, object storage, CDN)?

Environment Setup

• What is the branching strategy (e.g., trunk-based, GitFlow, main + feature branches)?
• What commit convention is used (Conventional Commits, custom, none)?
• Which pre-commit hooks are configured and with which tools (Husky, lint-staged, pre-commit)?
• What are the exact env file names (.env, .env.local, .env.staging)?
• Which environment variable categories are required vs optional (no values, just categories)?
• What CI/CD provider is used and what jobs run (lint, typecheck, test, build, deploy)?

Backend

• What ORM or query builder is used?
• What authentication library and token/session strategy is in use?
• What validation library is used and where is validation applied (request layer, service layer)?
• What is the file storage solution (S3, GCS, local disk, CDN-backed)?
• What email provider is used (SendGrid, SES, Resend, Postmark)?
• What logging and error-tracking tools are in use (Sentry, Datadog, Logtail)?
• What job queue or scheduler is used (BullMQ, Celery, pg-boss, cron)?
• What caching layer is used (Redis, in-memory, CDN edge cache)?
• What are the rate limiting rules and where are they enforced?

Frontend

• What routing library or framework convention is used (file-based, React Router, TanStack Router)?
• What state management approach (Zustand, Redux Toolkit, Jotai, React Query/TanStack Query, server state only)?
• What form library and validation schema tool (React Hook Form + Zod, Formik + Yup, native)?
• What toast or notification library?
• What SEO implementation approach (Next.js Metadata API, react-helmet, SSG, SSR)?
• What analytics provider (GA4, PostHog, Mixpanel, Plausible)?
• What asset optimization strategy (framework image component, sharp, manual WebP pipeline)?

Testing

• What unit testing framework and assertion library (Jest, Vitest, pytest)?
• What E2E testing tool (Playwright, Cypress, Puppeteer)?
• What is the code coverage threshold, if any?
• What accessibility audit tool (axe-core, Lighthouse CI, manual review)?
• What security testing approach (OWASP ZAP, manual pen test, automated scan)?

Legal & Compliance

• What GDPR/CCPA mechanisms are required (consent management platform, cookie banner library)?
• Where are legal documents hosted (in-app routes, external URL)?
• What license applies to the codebase (MIT, Apache 2.0, proprietary)?

Deployment

• What is the production environment setup (Docker + Kubernetes, serverless functions, managed PaaS, VMs)?
• What domain registrar and DNS provider are used?
• How is SSL/TLS provisioned (Let's Encrypt, cloud-managed certificate, manual)?
• What CDN provider and configuration approach (origin rules, cache headers, edge functions)?
• What monitoring and alerting stack (Datadog, Grafana + Prometheus, PagerDuty, Uptime Robot)?
• What is the backup strategy (frequency, storage location, retention period)?
• What is the rollback mechanism (blue-green deployment, feature flags, manual git revert, image pinning)?
• What post-deployment smoke tests or health checks are run?

---

After Phase 2 responses, document all confirmed answers in tech-details.md. Place unresolved items in the ## Open Technical Questions section with a note on what decision is needed.

File Responsibilities

tech-details.md owns:

• stack and runtime versions
• cost estimation at the infrastructure and service level
• architecture overview
• project structure and ownership boundaries
• data models and DB schema
• API shape, versioning, and documentation approach
• auth and permissions model
• AI workflow design
• technical constraints
• integrations (third-party services and APIs)
• local development environment setup
• package and dependency management
• secrets handling shape (env file names, required variable categories, validation location - not values)
• formatting, linting, typechecking, and testing tools, config files, and commands
• pre-commit hooks and editor config
• CI/CD pipelines and required verification gates
• build tools and asset pipeline
• deployment and runtime assumptions
• production infrastructure
• domain, DNS, HTTPS, and CDN setup
• monitoring, logging, alerting, backup, and rollback strategy
• file upload and storage approach
• email and notification infrastructure
• caching and background job strategy
• rate limiting and throttling approach
• SEO and analytics implementation details
• legal and compliance implementation details (not the legal text itself)
• accessibility implementation requirements (WCAG target level, audit tooling)
• cross-browser and device support targets
• performance and scalability constraints
• important implementation decisions
• security-relevant technical details
• schema or API versioning and migration notes

tech-details.md does not own:

• product vision
• target users
• feature wishlists
• MVP explanation
• roadmap phases
• task checklists
• backlog ordering
• recent work log
• project memory summaries
• actual legal document text (Privacy Policy body, Terms of Service body)
• secret values

Those belong in:

• idea.md for product intent
• plan.md for tasks and roadmap
• project-state.md for compact current state and pointers

Update Rules

When updating tech-details.md:

• Keep it factual and implementation-oriented.
• Do not invent architecture.
• Treat requests like "make initial project structure", "create project structure", or "write project structure" as requests to document the structure inside tech-details.md.
• Do not create, move, rename, or delete project files or directories unless the user explicitly asks for filesystem changes outside the tech-details.md maintenance task.
• If a technical decision is missing, propose it first instead of silently adding it.
• Prefer concise sections over long explanations.
• Remove stale or contradictory technical details.
• Preserve existing decisions unless the user explicitly changes them.
• Cross-reference other files instead of duplicating their content.
• Keep project structure summaries selective; document important directories and boundaries, not full file trees.
• Keep examples minimal unless they clarify API, schema, or workflow shape.
• Mark uncertain items as open questions instead of decisions.

Environment And Quality Gates

When documenting local setup, formatting, linting, typechecking, testing, or CI:

• Discover repo facts from source files before writing commands: package manifests, lockfiles, tool config files, Makefiles, task runners, Docker files, compose files, CI workflows, and existing docs.
• Document the package manager and runtime version source when confirmed, such as .nvmrc, .node-version, .python-version, pyproject.toml, packageManager, lockfiles, or Docker base images.
• Document environment variable handling at the shape level: env file names, required variable categories, secret storage assumptions, and validation location. Do not include secret values.
• Document the actual formatting and linting tools as required facts when present, not only their commands. Include config files and integration points such as eslint.config.*, .eslintrc*, .prettierrc*, prettier.config.*, biome.json, ruff.toml, pyproject.toml, editor settings, pre-commit hooks, package scripts, Make targets, and CI jobs.
• Record exact format, lint, typecheck, test, build, and migration commands only when they are present in project files or have been confirmed by the user.
• If a command is inferred but not confirmed, place it under Open Technical Questions or label it as proposed instead of presenting it as a project fact.
• Keep quality-gate notes implementation-oriented: what runs locally, what runs in CI, what must pass before merge/release, and which checks are intentionally absent.
• Do not run dependency installation, formatters, linters, tests, migrations, or builds merely to maintain tech-details.md unless the user explicitly asks for verification. Reading config is enough for documentation updates.

Required Checks

Before writing changes, verify:

• Does this belong in tech-details.md?
• Does it conflict with project-state.md?
• Does it conflict with plan.md task status?
• Does it duplicate idea.md product details?
• Is this confirmed, proposed, or uncertain?
• If this is initial creation, have I asked whether Phase 1 and Phase 2 discovery must be run before creating tech-details.md, unless the user already explicitly answered?
• Have I run Phase 1 and Phase 2 discovery if required for this creation or major update, and are there still unknowns to resolve before writing?
• Have I documented formatting and linting tools and config locations, such as ESLint and Prettier when present, instead of only listing commands?
• Are local setup and quality-gate commands confirmed by repository files or the user?
• Am I documenting secret names and handling without exposing secret values?
• Am I about to change files other than tech-details.md? If yes, did the user explicitly request those filesystem changes?

Suggested Structure

Use this structure unless the project already has a better one:

# Tech Details

## Stack

## Cost Estimation

## Project Structure

## Architecture

## Data Model

## API Shape

## Auth & Permissions

## AI Workflow

## Integrations

## UI & Design System

## Frontend Architecture

## SEO & Analytics

## Environment Setup

## Quality Gates

## Security

## Performance & Scalability

## Legal & Compliance Implementation

## Runtime / Deployment

## Monitoring, Observability & Recovery

## Constraints

## Technical Decisions

## Open Technical Questions