Add product design spec: defining user value and positioning

[vdavid]

Summary

Add a comprehensive product design document that outlines the strategic direction for the tool based on user research and product positioning insights. This document captures the results of conversations with a product designer and AI agent, identifying key gaps and opportunities for the product.

Key Changes

• Added docs/specs/product-design.md — A detailed product design specification that includes:
  • Background on the need to define user value before public launch
  • Insights from product designer conversations identifying the "data vs. insight" gap
  • Analysis of the core user persona (reflective developers/technical founders)
  • The stratigraphy metaphor as a framework for understanding codebase evolution
  • Positioning strategy around the AI development era
  • Five concrete action items for product development:
    1. Build an interpretation layer to narrate data patterns
    2. Add reference dataset of well-known projects for contextual comparison
    3. Add AI era markers (Copilot, Agentic) as chart boundaries
    4. Implement OG share cards for social sharing
    5. Refine product positioning from descriptive to narrative-driven

Notable Details

The document establishes that the tool's core value isn't just showing metrics, but helping developers understand the "biography" of their codebase — reading the story recorded in code growth patterns, language choices, and velocity changes. This positions the tool as a lens for understanding software development in the AI age, rather than a generic stats dashboard.

https://claude.ai/code/session_01Fe1khakaqCvnSPLW2ncy45