ryanwold.net - Civic Tech, Bitcoin, and Open Government Innovation

Show

An entry

Get it down. Make it good. Share it.

Title

Text

hi, what is your preferred way to approach a relatively large application, in terms of specifying intent and application
  behavior consistently? often, i have resorted to informal approaches and declarations that may be inconsistent within and/or
  across sessions. how can we work more effectively together over a longer time period?

• A good way to make a big app feel “coherent” over time is to give us a few stable anchors that everything else hangs off of.
  Concretely:

1. Capture intent in a few durable artifacts

- Product / behavior spec: One living doc in the repo (e.g. docs/PRODUCT_OVERVIEW.md) that answers:
      - What the app is for; who uses it.
      - Core flows (e.g. “Explore embeddings”, “Discover Topics”, “Label clusters”).
      - Non‑negotiables: UX tone, performance targets, privacy constraints.
  - Architecture + data model: Short docs like:
      - docs/ARCHITECTURE.md (major contexts, boundaries, “who owns what”).
      - docs/DATASETS.md, docs/HIERARCHICAL_CLUSTERING.md (you already have some of these).
  - Decision log: Lightweight ADRs (docs/adr/xxxx-*.md) for key choices:
      - “Cluster naming is always derived from LLM label > keyword label > description.”
      - “Explorer always filters by Conversation.source for dataset-specific routes.”

If you tell me “treat these docs as the source of truth,” I can align changes and push back when new requests contradict them.

2. Make behavior explicit with tests and routes

- Use tests as contracts:
      - For anything important (cluster naming, explorer filters, topic regeneration), add a test that describes the behavior in
        plain language.
      - When you ask for a change, reference the behavior: “Update the behavior described in initial_clusters_llm_test so that…”.
  - Treat URLs as behavioral anchors:
      - Keep a simple index like docs/ROUTES.md listing key routes and what they’re for.
      - In prompts, refer to behavior via route: “On /datasets/:id/explore, the language filter should…”

3. Prompt style that scales across sessions

When you open a new session or a bigger task, a short template works well:

- Context (1–3 bullets)
      - “We’re building CDCS, a Phoenix 1.8 app for conversational datasets.”
      - “We use LiveView and Tailwind; layout should stay consistent with X.”
      - “Clusters and topics are modeled via Taxonomy/Topic.”
  - Goal
      - “I want users to be able to X from Y page.”
  - Constraints / preferences
      - “Use existing clustering pipeline; no new deps.”
      - “Preserve current URL structure; no breaking routes.”
  - Where to plug in (optional but powerful)
      - “This likely touches DatasetLive.Show, ExplorerLive.Index, and InitialClusters.”

If you can copy‑paste a short “session preamble” like that each time, I can keep context aligned even if we jump around.

4. Use consistent vocabulary

- Pick stable names for core concepts and stick to them:
      - “Cluster” vs “Topic” vs “Taxonomy” vs “Facet”.
      - “Analysis job” vs “Enrichment job”.
  - If we redefine something, capture it in a doc or ADR. I can then treat the doc as canonical and normalize new changes to that
    vocabulary.

5. Layered changes: describe “what” first, “where” second

For bigger features, it helps to separate:

- What behavior changes:
      - “When Discover Topics completes for model M on dataset D, show ‘View Topics’ next to ‘Reset’ and link into /datasets/D/
        clusters?model=M.”
  - Where:
      - “This affects the Enrichment table on /datasets/:id, specifically the embedding rows.”

That keeps intent clear and makes it easier to avoid accidental regressions elsewhere.

6. Long‑term collaboration pattern

If you’d like us to work smoothly over time, we can:

- Treat certain files as contracts:
      - AGENTS.md, docs/*, key tests, core LiveViews.
  - Any time you give a new requirement, we either:
      - Update the contract (doc/test) first, then code; or
      - Explicitly say “this is a one‑off deviation, do not generalize.”
  - Periodically (e.g. after a chunk of work), have me summarize the current conventions:
      - “How cluster naming works now.”
      - “How explorer filtering works now.”

Status

Series