RestartCrew

DECISIONS

2026-03-15 — Hosting: GitHub Pages instead of VPS/Docker (no external services)

• Context: Development plan (Milestone 13) specified provisioning a VPS (Hetzner, ~€5/month) with Docker + Caddy, and setting up a separate production Supabase instance. Owner clarified: no external services, only direct hosting via GitHub. Existing Supabase Nano instance is sufficient.
• Options considered:
  1. Keep VPS/Docker/Caddy plan — requires external server, monthly cost, infrastructure management
  2. Switch to GitHub Pages with static export — zero cost, zero infrastructure, direct GitHub integration
• Chosen option: GitHub Pages with Next.js static export. GitHub Actions builds and deploys on merge to main. Existing Supabase Nano instance continues as the backend. No VPS, no Docker deployment, no Caddy, no separate production Supabase.
• Reason: Owner explicitly requested no external services. GitHub Pages is free, provides automatic HTTPS, supports custom domains, and integrates directly with the repository. Supabase Nano already handles all backend needs (database, auth, storage). This eliminates infrastructure complexity and cost entirely.

2026-03-15 — Consolidation cleanup: removed tombstone redirect files

• Context: After consolidating PRODUCT_SPEC.md and strategy-and-actionplan.md into docs/MAIN_DEVPLAN_RESTARTCREW.md, both original files remained as tombstone redirects. With the main dev plan fully comprehensive (13 milestones, 71 tasks, design system, technical decisions), the tombstones add no value and cause confusion about which files matter.
• Options considered:
  1. Keep the tombstone files as redirects indefinitely
  2. Delete the tombstones now that all references point to MAIN_DEVPLAN_RESTARTCREW.md
• Chosen option: Delete both tombstone files (dev/strategy/strategy-and-actionplan.md and docs/PRODUCT_SPEC.md). Historical references in DEVLOG.md and DECISIONS.md are preserved with context.
• Reason: The main development plan is the established single source of truth. Keeping empty redirect files creates unnecessary noise in the repository and contradicts the goal of a clean, navigable project structure. INDEX.md already points to MAIN_DEVPLAN_RESTARTCREW.md for all purposes.

2026-03-14 — Plan documentation structure

• Context: We needed to start the development plan in the repository docs folder.
• Options considered:
  1. Keep plan only in one large file
  2. Add main plan + operational tracking docs
• Chosen option: Add docs/PRODUCT_SPEC.md (originally MVP1_DEV_PLAN.md) plus DEVLOG, DECISIONS, and ROADMAP scaffolding.
• Reason: Matches the execution model in the approved plan and enables iterative AI-agent delivery.

2026-03-14 — Use semantic design tokens + interaction quality bar

• Context: The original plan had high-level design guidance but needed implementation-ready specs to deliver a premium visual/interaction experience.
• Options considered:
  1. Keep broad visual guidance only
  2. Add strict design token system, motion rules, component specs, and QA scorecard
• Chosen option: Added a detailed design deep dive section with tokenized foundations and a per-screen quality scorecard.
• Reason: Reduces ambiguity for implementation, improves consistency across contributors, and raises UI quality with measurable acceptance criteria.

2026-03-14 — Create Strategy and Action Plan as hybrid execution document

• Context: The existing PRODUCT_SPEC.md (then MVP1_DEV_PLAN.md) is a comprehensive product specification but has critical gaps for agent-driven execution: tech stack contradictions, missing concrete decisions, phases too coarse for step-by-step work, and no verification checkpoints.
• Options considered:
  1. Extend PRODUCT_SPEC.md with execution details inline
  2. Create a separate strategy + execution plan document in dev/strategy/
  3. Break the plan into many small ticket-like files
• Chosen option: Created dev/strategy/strategy-and-actionplan.md — a standalone hybrid document with critical assessment, strategic decisions, and atomic step-by-step phases with verification checkpoints.
• Reason: Keeps PRODUCT_SPEC.md as the product spec (what to build) and the action plan as the execution guide (how to build it, in what order, with what verification). Separation prevents the product spec from becoming cluttered with implementation details. The dev/strategy/ location matches the repository structure for internal planning documents.

2026-03-14 — Tech stack: Next.js App Router + GitHub Pages (no Vercel/Netlify/VPS)

• Context: Three documents had conflicting tech stack descriptions. AGENTS.md said “static web app / GitHub Pages / Vercel / Netlify”, PRODUCT_SPEC.md said “Next.js / Vercel”, and existing code used Vite patterns. Owner clarified: no Vercel/Netlify, lean toward PRODUCT_SPEC tech choice.
• Options considered:
  1. Vite + React (static SPA) — simple, deploys to static hosting
  2. Next.js App Router + Vercel — SSR benefits, but owner rejected Vercel
  3. Next.js App Router + Docker on VPS — SSR benefits, full infrastructure control, no vendor lock-in
• Chosen option: Next.js App Router + TypeScript + Tailwind CSS, deployed via GitHub Pages (static export). (Originally Docker/VPS was chosen, later updated to GitHub Pages — see 2026-03-15 decision.)
• Reason: Next.js provides SSR for SEO on landing/public pages, React Server Components for performance, and a mature ecosystem. GitHub Pages provides free, zero-maintenance hosting with automatic HTTPS and custom domain support.

2026-03-14 — CSS framework: Tailwind CSS

• Context: PRODUCT_SPEC.md mentioned “utility-first styling” but no specific framework was chosen.
• Chosen option: Tailwind CSS v4 with custom theme matching project design tokens.
• Reason: Industry standard for utility-first CSS, first-class Next.js support, excellent responsive utilities, well-understood by developers and AI agents.

2026-03-14 — Test framework: Vitest + Playwright

• Context: No test framework had been chosen.
• Chosen option: Vitest for unit/integration tests, React Testing Library for component tests, Playwright for E2E tests.
• Reason: Vitest is fast, TypeScript-native, jest-compatible. Playwright is reliable for cross-browser E2E testing and auth flow testing.

2026-03-14 — Auth providers: Email + Google OAuth

• Context: No specific OAuth providers had been selected.
• Chosen option: Supabase Auth with email/password + Google OAuth.
• Reason: Email/password is essential for privacy-conscious users. Google OAuth covers the widest user base and is most trusted. Additional providers can be added later.

2026-03-14 — Comprehensive scope (not reduced MVP)

• Context: Previous strategy suggested splitting into MVP1a/MVP1b to reduce time-to-launch. Owner clarified: no MVP labeling, scope should be comprehensive.
• Chosen option: Full v1 scope with 13 milestones covering all features: landing page, auth, onboarding, forum, profiles, search, notifications, moderation, admin tools, analytics, and production deployment.
• Reason: Owner wants a complete, professional product at launch. Milestones provide natural stopping points for review without artificially limiting scope.

2026-03-14 — Design reference: Teamblind.com

• Context: Needed a concrete design reference for the forum UX beyond abstract guidelines.
• Chosen option: Use Teamblind.com as the primary forum UX reference. Study their anonymous posting, community structure, thread density, and navigation patterns. Adapt for RestartCrew’s warmer emotional tone and focused niche.
• Reason: Teamblind has proven forum UX with strong anonymous posting and professional community features — core to RestartCrew’s identity. RestartCrew differentiates with emotional warmth, support focus, and community safety emphasis.

2026-03-14 — Concrete design token values

• Context: Previous plan defined semantic token names but no actual values (hex colors, font families, sizes).
• Chosen option: Defined complete design system with Inter font, warm neutral palette (off-white canvas, calm blue primary, warm amber secondary), spacing scale, radius scale, shadow tokens, and motion timing. Values documented in strategy-and-actionplan.md Part 2.
• Reason: Concrete values enable immediate implementation without blocking on visual direction. Values can be adjusted during Milestone 2 review. Starting point chosen for warm, professional, trustworthy feel matching the product’s emotional design principles.

2026-03-14 — Early-stage metrics strategy (no view counts at launch)

• Context: Metrics like “X views” or “X people saw this” are counterproductive when the community is small. “2 views” signals emptiness and discourages engagement.
• Options considered:
  1. Show all metrics from day one (including view counts, trending)
  2. Hide all engagement metrics
  3. Use early-stage appropriate metrics at launch, switch to scale-aware metrics when thresholds are reached
• Chosen option: Design all post/thread metadata for early-stage viability. Show: reply count, time since activity, unique participants, category/profession chips, author status badges, “Marked helpful” indicators. Avoid: view counts, trending indicators, upvote/downvote counts, follower counts. Collect all data from day one (for internal analytics), but only expose numbers in UI when they become meaningful (~200+ active users threshold).
• Reason: Every visible metric must feel meaningful even with single-digit users. “Be the first to reply” is a call-to-action; “0 views” is a death signal. Data collection happens regardless, so switching to richer metrics later costs nothing.

2026-03-14 — Next-level user profiles (journey documents)

• Context: Generic forum profiles are just info pages. RestartCrew’s target users are going through career transition — the profile should tell that story.
• Options considered:
  1. Standard profile (name, bio, avatar, posts list)
  2. Extended profile with skills and status
  3. Journey-oriented profile with AI Impact Story, three-category skills portfolio, community badges, status evolution, and future milestones/goals
• Chosen option: Two-tier profile system. Tier 1 (launch): Identity & Context, AI Impact Story (structured narrative), Skills Portfolio (have/building/want), Community Contributions (helpfulness, badges). Tier 2 (post-launch): Journey Timeline, Personal Goals, Wins & Celebrations, Connection & Availability.
• Reason: Profiles are the emotional core of the product. A “journey document” inspires visitors, builds credibility, and creates connection — differentiating RestartCrew from every other forum. Tier 1/Tier 2 split ensures launch isn’t blocked by post-launch features.

2026-03-14 — “Helpful” marking system on replies

• Context: Need a lightweight engagement metric that works at any scale and rewards supportive behavior.
• Options considered:
  1. Upvote/downvote (Reddit-style) — problematic for support community; downvotes can feel hostile
  2. Reactions (emoji-style) — too casual/social-media for this context
  3. “Helpful” marking — single positive signal, framed as value recognition
• Chosen option: “Helpful” button on replies. Thread author and other users can mark replies as helpful. Count feeds into community badges and profile reputation.
• Reason: Frames engagement as support, not popularity. Works at any scale (even 1 helpful mark is meaningful). Creates a virtuous cycle where helpful behavior is recognized.

2026-03-14 — Expanded Teamblind.com design reference

• Context: Owner confirmed Teamblind.com should be studied closely for design patterns. Much of the same design approach can be adopted.
• Chosen option: Expanded the Teamblind.com reference with specific patterns to adopt: anonymous posting flow, thread card density, thread detail layout, category navigation, company/profession verification display, mobile UX. Added adaptation notes for RestartCrew’s warmer tone. Added Teamblind profile study for identity display.
• Reason: Having specific patterns to study (not just “look at Teamblind”) gives the design phase concrete starting points. The detailed comparison of what to adopt vs. how to adapt ensures RestartCrew maintains its own identity while learning from proven UX.

2026-03-14 — Documentation restructuring before build phase

• Context: Before starting Milestone 1 execution, reviewed all MD files for structure clarity, navigation, and naming. Found the docs are well-organized with no contradictions, but had practical improvements to make.
• Options considered:
  1. Leave as-is — structure is already functional
  2. Minor improvements — rename unclear files, add navigation hub, add workflow guide
  3. Major restructure — merge/split documents, reorganize folders
• Chosen option: Minor improvements:
  • Renamed MVP1_DEV_PLAN.md → PRODUCT_SPEC.md — the file is a product specification, not a “dev plan”. The new name matches its role and avoids confusion with the execution plan in dev/strategy/.
  • Created docs/INDEX.md — a navigation hub so any reader can quickly find the right document.
  • Created docs/HOW_WE_WORK.md — explains the agent workflow and document update cadence.
  • Added milestone progress tracker to docs/DEVLOG.md — gives at-a-glance status without opening the strategy doc.
  • Added cross-references to README.md.
• Reason: These changes reduce friction for anyone entering the project. The rename eliminates the question “is the dev plan the same as the strategy doc?” The navigation hub prevents time wasted searching for the right file. The progress tracker gives instant milestone status. None of these changes alter the content or structure of the docs — they just make it more navigable.