write-tech-spec

name	write-tech-spec
description	Write a TECH.md spec for a significant Hubble feature after researching the monorepo architecture. Use when the user asks for a technical spec, implementation plan, architecture plan, or package/app/module breakdown tied to product behavior.

write-tech-spec

Write a TECH.md spec for a significant Hubble feature.

Overview

The tech spec is the implementation approach as scannable bullets grounded in real code, plus the test plan. A reviewer should be able to scan it in under a minute and spot the risky decision. It is not a build log or a tutorial: every bullet either names a change to make or a decision a reviewer might push back on.

Prefer a sibling PRODUCT.md first (write-product-spec). Reference its flows instead of restating user-facing behavior.

Write specs to specs/<id>/TECH.md, matching the sibling product spec id. specs/ should contain only id-named directories as direct children.

Only create a GitHub issue when the user explicitly asks. This repo uses GitHub Issues on bholmesdev/hubble.md via gh; see docs/agents/issue-tracker.md.

When To Use

Use for changes that span multiple modules, affect shared packages, change sync/workspace behavior, or introduce new data flow. Skip for single-file UI fixes.

Research Before Writing

Read the product spec, then inspect the actual code. Do not guess about architecture when the code can be read:

• CONTEXT.md for domain terms and relevant docs/adr/* for constraints.
• The affected source under apps/desktop, apps/www, packages/editor, packages/ui, packages/sync, packages/sync-backend, packages/convex-client, packages/cli.
• Existing helpers and primitives that already do part of the job. Naming an existing unused helper beats proposing a new one.

Structure

1. Approach — the core of the spec. Bullets stating what changes where, each grounded in real code: New shared helper classifyHref(href) used in three places: ..., No parser/serializer changes; links round-trip as-is, Reuse normalizePath from apps/desktop/src/lib/filePath.ts (exists but unused here). Group by concern (renderer, main process, shared package) when the change spans layers. Explicitly call out what does NOT change when a reviewer would expect it to. State a tradeoff in one line only where more than one approach is plausible.
2. E2E test plan — required. Derive it from the PRODUCT.md flows:
   • Desktop: exact flows to drive in the running app per .agents/skills/test-desktop-app/SKILL.md — the Workspace state to open, the actions to perform, and the visible result to confirm. Name screens and controls, not "manually test the UI".
   • Web: the same flows via the dev server with ?test=1 when the behavior is cross-surface (requires VITE_TEST_CONVEX_URL and VITE_TEST_WORKSPACE_ID in apps/www/.env.local).
   • Unit/integration tests worth writing, named by module.
   • Commands: pnpm check for iteration, pnpm build:desktop for final confidence.

Optional, only when they earn their lines:

• Risks — real regressions, data loss, or sync hazards, one bullet each with the mitigation.
• Diagram — Mermaid only when it explains data flow faster than prose.
• Follow-ups — deferred slices.

Do not include boilerplate sections: no affected-package inventories, module-architecture essays, step-by-step build ordering, or parallelization plans. If a package matters, it shows up naturally in the Approach bullets' file paths.

Writing Guidance

• Ground every bullet in code you read: name files, functions, and existing patterns. Prefer local paths with line numbers; use commit-pinned GitHub links only when the spec will be read outside a checkout.
• Use project vocabulary from CONTEXT.md.
• Reuse existing design-system primitives and nearby patterns before proposing new ones.
• Use logical CSS spacing props in frontend plans: margin/padding inline/block/start/end, not physical left/right/top/bottom.
• Target 30-80 lines total. If a bullet doesn't change what the implementer types or what the reviewer checks, cut it.

Keep Current

Update TECH.md in the same PR when the approach, risks, or test plan changes. The checked-in spec should describe what ships.

Related Skills

• write-product-spec
• to-issues
• grill-with-docs