Feature Implementation: Research, Prompt, and AI-First Loop¶

This document describes how most features are implemented in this project: start with a research question, turn that into a prompt-creation question, then run an AI-first development loop to implement the feature end-to-end.

1. Overview: The Three-Step Pattern¶

Feature work follows a consistent three-step pattern so that implementation is informed by research and guided by a clear, AI-executable prompt.

2. Step 1: Research Question¶

Before implementing a feature or integrating a technology, we ask a research question. The goal is to gather options, trade-offs, and constraints so the subsequent prompt and implementation are well-informed.

Why research first?

• Avoids rework: the implementation prompt can reference the chosen approach and constraints.
• Creates a paper trail: future changes can refer back to the research.

3. Step 2: Prompt-Creation Question¶

Once the topic is researched (or when the approach is already clear), the next step is to ask for a prompt: a single, self-contained document that instructs an AI to implement the feature. The “question” is the request to create that prompt.

Prompt-creation question examples:

• "Using the research in docs/03-architecture/research/clickhouse-grafana-logging-research.md, write a prompt that instructs an AI to implement centralized logging with ClickHouse and Grafana in our NestJS stack."
• "Create a prompt for implementing Phase 4: Fulfillment Loop, referencing the requirements and Phase 3 context."

4. Step 3: AI-First Development Loop¶

The implementation step runs an AI-first development loop: the AI (or developer using the prompt) implements the feature, runs tests and lint, fixes issues, and iterates until acceptance criteria are met. The prompt is the single source of instruction for each run.

Loop in context: the prompt sits at the center; the agent (human or AI) iterates around implement → build → test until done.

5. Full Flow: Research → Prompt → Loop¶

End-to-end, the flow looks like this:

6. Where Artifacts Live¶

7. Summary Diagram¶

One diagram tying research, prompt creation, and the AI-first loop together:

This pattern keeps features aligned with prior research and a single, clear prompt, while the AI-first loop ensures that implementation is validated by build and tests before being considered done.