PRD Workflow

Een PRD-workflow helpt je gestructureerd van idee naar resultaat werken. Je beschrijft helder wat gebouwd moet worden en waarom. Dit geeft het team duidelijkheid. Ook kunnen LLMs en agents direct met de requirements aan de slag. Zo voorkom je misverstanden en werk je sneller naar het gewenste resultaat.

MCP Workflow Beschikbaar

Voor Claude Code gebruikers is er ook een geautomatiseerde MCP versie van deze workflow beschikbaar. Deze elimineert handmatig copy/pasten en laadt automatisch de juiste context.

Wanneer te gebruiken

Gebruik de PRD-workflow wanneer je:

• Een complexe feature wilt implementeren met meerdere requirements
• Wilt voorkomen dat belangrijke details over het hoofd worden gezien
• Een gestructureerde aanpak wilt voor feature development
• Heldere specificaties nodig hebt voordat je begint met implementeren

Hoe het werkt

De PRD-workflow bestaat uit drie hoofdfasen:

1. Feature beschrijving - Definieer wat en waarom
2. PRD generatie - Automatisch gedetailleerd document maken
3. Implementatie - Stap voor stap uitvoering

Elke fase bouwt voort op de vorige en zorgt voor volledigheid.

Procesoverzicht

Stap 1: Feature en requirements

Een LLM kan niet doeltreffend werken zonder een duidelijke opdracht. Daarom beginnen we met het beschrijven van de feature en requirements.

Beschrijf je feature en requirements in dit formaat, je hebt dit in de volgende stap nodig.

Template

Feature:
...

Requirements:
- ...

Voorbeeld 1

Feature:
Github Actions CI-pipeline voor deze repository

Requirements:
- Voer in de CI-pipeline de tests, linting en build uit pre-commit uit
- De CI-pipeline moet uitgevoerd worden op elke push naar de main branch
- De CI-pipeline moet uitgevoerd worden op elke pull request naar de main branch

Voorbeeld 2

Feature:
Codebase ombouwen naar NextJS project

Requirements:
- De codebase is nu een nextjs applicatie
- De huidige pagina's moeten blijven werken

Andere voorbeelden van Requirements

Voorbeeld 1: Setting om automatische code reviews in en uit te schakelen per repository

Gevraagde feature:

Feature:
Automatische code reviews instellen per repository

Requirements:
- Het moet mogelijk worden automatische code reviews in en uit te schakelen per repository via de front-end.
- Dit instellen kan alleen in de admin interface
- Voor de code review geldt een vaste basisprompt die in een .md file in deze repository geplaatst wordt.
- Het moet mogelijk zijn om per repository extra aandachtspunten voor de code review te plaatsen. Dit kan een vrije tekstveld worden waarvan de waarde in de DB opgeslagen wordt.

Uitkomst PRD: Setting om automatische code reviews in en uit te schakelen per repository

# Product Requirements Document: Instellingen voor Automatische Code Reviews per Repository

## 1. Feature Overzicht
**Feature:** Configuratie-instellingen voor automatische code reviews per repository.
**Doel:** Administrators de mogelijkheid bieden om de instellingen voor (toekomstige) geautomatiseerde code reviews per repository te configureren, ter voorbereiding op de verbetering van codekwaliteit en consistentie. De daadwerkelijke uitvoering van de code review valt buiten de scope van dit PRD.

## 2. Functionele Vereisten

### FV1: Configuratie op Repositoryniveau (Admin Interface)
*   **FV1.1:** Administrators moeten de mogelijkheid hebben om de *intentie* tot automatische code reviews per repository aan of uit te zetten via een specifieke sectie in de admin interface. Dit activeert nog niet de review zelf, maar slaat de voorkeur op.
*   **FV1.2:** De interface moet duidelijk de huidige status (gepland voor review / niet gepland voor review) per repository weergeven.

### FV2: Beheer Basisreviewprompt Locatie/Referentie
*   **FV2.1:** Een standaard basisprompt voor code reviews zal worden opgeslagen als een Markdown-bestand (bijv. [`code_review_basis_prompt.md`](code_review_basis_prompt.md:0)) binnen deze hoofdrepository ([`/Users/rtuin/Sites/repo-tools.zonneplan`](/Users/rtuin/Sites/repo-tools.zonneplan)). Dit PRD dekt niet het beheer of de inhoud van dit bestand, enkel de wetenschap dat het bestaat en gebruikt zal worden.
*   **FV2.2:** Het systeem (in een later stadium) zal de inhoud van dit bestand gebruiken als de fundamentele set instructies.
*   **FV2.3:** Wijzigingen aan dit basispromptbestand zijn globaal van toepassing (in een later stadium).

### FV3: Repository-specifieke Reviewinstructies
*   **FV3.1:** Binnen de admin interface moeten administrators voor elke repository aanvullende, repository-specifieke instructies of aandachtspunten kunnen opgeven die bedoeld zijn voor de (toekomstige) geautomatiseerde code review.
*   **FV3.2:** Deze invoer dient een vrij tekstveld te zijn.
*   FV3.3: De repository-specifieke instructies moeten veilig worden opgeslagen in de database van de applicatie, gekoppeld aan de desbetreffende repository.
*   **FV3.4:** De opgeslagen basisprompt-referentie en repository-specifieke instructies moeten beschikbaar zijn voor een toekomstig review-uitvoeringsmechanisme.

## 3. Gebruikersinterface (UI/UX) Overwegingen (Admin Interface)
*   **UI1:** Een duidelijke schakelaar (toggle switch) of vergelijkbaar besturingselement voor het aan-/uitzetten van de *intentie* tot review per repository.
*   **UI2:** Een tekstveld (text area) voor het invoeren van repository-specifieke reviewinstructies, met duidelijke labels en eventuele karakterlimieten.
*   **UI3:** Een informatieve melding die aangeeft waar de basisprompt wordt beheerd (bijv. "De algemene basisprompt wordt beheerd via het [`code_review_basis_prompt.md`](code_review_basis_prompt.md:0) bestand in de applicatie repository").

## 4. Technische Overwegingen
*   **TO1: Databaseschema:**
    *   Er is een aanpassing nodig aan de `repositories` tabel (of een nieuwe gerelateerde tabel) om de volgende velden per repository op te slaan:
        *   `auto_review_setting_enabled` (BOOLEAN, default: FALSE)
        *   `repository_specific_review_prompt` (TEXT, nullable)
*   **TO2: Prompt Data Beschikbaarheid:**
    *   De opgeslagen instellingen (status en specifieke prompt) moeten via een API of interne service beschikbaar zijn voor een toekomstig code review mechanisme. De logica om de basisprompt te lezen en te combineren valt buiten dit PRD.
*   TO3: Beveiliging:
    *   Toegang tot de configuratiepagina voor review-instellingen moet beperkt zijn tot gebruikers met administratorrechten.
    *   Inputvalidatie en -sanering moeten worden toegepast op het vrije tekstveld voor repository-specifieke instructies om XSS en andere injectie-aanvallen te voorkomen.
*   TO4: Performance & Schaalbaarheid (Instellingen):
    *   Het opslaan en ophalen van deze instellingen moet performant zijn, maar de directe impact van review-uitvoering is buiten scope.
*   **TO5: Foutafhandeling:**
    *   Duidelijke feedback aan de admin als er problemen zijn met het opslaan/ophalen van repository-specifieke instellingen.

## 5. Buiten Scope (voor deze initiële versie)
*   **De daadwerkelijke uitvoering van de geautomatiseerde code review.**
*   Het creëren, wijzigen of valideren van de inhoud van het [`code_review_basis_prompt.md`](code_review_basis_prompt.md:0) bestand.
*   Gebruikers (niet-admins) die review-instellingen kunnen aanpassen.
*   Meerdere, selecteerbare basisprompts per repository.
*   Real-time feedback of suggesties in een IDE tijdens het coderen.
*   Gedetailleerde logging of auditing van wijzigingen in review-instellingen (basis logging wel).
*   Versiebeheer voor de repository-specifieke instructies.

## 6. Succescriteria
*   Administrators kunnen succesvol de instelling voor automatische code reviews (aan/uit) per repository opslaan.
*   Administrators kunnen repository-specifieke aandachtspunten opslaan die bedoeld zijn voor een toekomstige review.
*   De opgeslagen instellingen (status en specifieke prompt) zijn correct en toegankelijk voor een later te implementeren review-mechanisme.

Voorbeeld 2: Genereren van deze Richard's prompts pagina's

Gevraagde feature:

Feature:
Nieuwe sectie genaamd "Richard's prompts" in deze documentatie website

Requirements:
- De nieuwe sectie moet op hetzelfde level als guides en roadmap staan
- Onder deze sectie komen in eerste instantie deze pagina's met placeholders: "PRD workflow" en "Code review" (plaats ook markdown codeblock placeholders waar ik de prompts in kan plakken)
- Op de pagina "PRD workflow" komt een korte uitleg over de PRD workflow, een prompt voor het schrijven van een product requirement document, een voorbeeld PRD (in markdown, collapsible block), en de prompt voor het implementeren van de PRD

Uitkomst PRD: Genereren van deze Richard's prompts pagina's

# PRD: "Richard's Prompts" Documentation Section

> Execute each task in the order given to create the new "Richard's Prompts" section in the documentation website.

## Task 1: Create New Top-Level Navigation Item 

- **Action:** Add a new top-level navigation item titled "Richard's Prompts".
- **Placement:** This item should appear in the main navigation at the same hierarchical level as the existing "Guides" and "Roadmap" sections.
- **File to modify:** (This will likely be a VitePress configuration file, such as `docs/.vitepress/config.js` or a theme configuration file, depending on your specific setup.)

## Task 2: Create "PRD Workflow" Page 

- **Action:** Create a new markdown file for the "PRD Workflow" page.
- **Location:** This file should be placed within a new directory structure, for example: `docs/richards-prompts/prd-workflow.md`.
- **Content:**
    1.  **Page Title:** `PRD Workflow`
    2.  **Introduction:** A brief explanation of what a Product Requirement Document (PRD) workflow entails and its benefits.
    3.  **Prompt for Writing a PRD:**
        ```md
        ### Prompt for Writing a PRD
        
        ```markdown
        <!-- Paste PRD Writing Prompt Here -->
        ```
        ```
    4.  **Example PRD:**
        ```md
        ### Example PRD
        
        <details>
        <summary>View Example PRD</summary>
        
        ```markdown
        # Example Product Requirement Document
        
        **Feature:** User Authentication
        
        **1. Introduction:**
           Brief overview of the feature and its purpose.
        
        **2. Goals:**
           - Allow new users to register for an account.
           - Allow existing users to log in to their account.
           - Allow authenticated users to log out.
        
        **3. User Stories:**
           - As a new user, I want to be able to create an account using my email and password, so that I can access the platform's features.
           - As an existing user, I want to be able to log in with my credentials, so that I can resume my activities.
           - As a logged-in user, I want to be able to log out securely, so that my session is terminated.
        
        **4. Functional Requirements:**
           - User registration form (fields: email, password, confirm password).
           - Password strength validation.
           - Login form (fields: email, password).
           - "Forgot password" link (functionality TBD in a separate PRD).
           - Logout button/link.
        
        **5. Non-Functional Requirements:**
           - **Security:** Passwords must be hashed. Input validation to prevent common vulnerabilities.
           - **Usability:** Clear error messages for registration and login failures.
        
        **6. Design Considerations (Optional):**
           - Links to UI mockups or wireframes if available.
        
        **7. Out of Scope:**
           - Social logins (Google, GitHub, etc.).
           - Two-factor authentication.
        
        **8. Open Questions:**
           - What is the policy for password recovery?
        ```
        </details>
        ```
    5.  **Prompt for Implementing the PRD:**
        ```md
        ### Prompt for Implementing the PRD
        
        ```markdown
        &lt;!-- Paste PRD Implementation Prompt Here --&gt;
        ```
        ```

## Task 3: Create "Code Review" Page 

- **Action:** Create a new markdown file for the "Code Review" page.
- **Location:** This file should be placed within the same new directory structure, for example: `docs/richards-prompts/code-review.md`.
- **Content:**
    1.  **Page Title:** `Code Review`
    2.  **Prompt for Code Review:**
        ```md
        ### Code Review Prompt
        
        ```markdown
        &lt;!-- Paste Code Review Prompt (e.g., the "Ultra Diff Review" prompt) Here --&gt;
        ```
        ```
        *(Note: The "Ultra Diff Review" prompt you provided earlier can be placed here.)*

## Task 4: Update Navigation Configuration 

- **Action:** Update the VitePress configuration file (e.g., `docs/.vitepress/config.js` or a sidebar configuration within `docs/.vitepress/theme/`) to include the new "Richard's Prompts" section and its child pages ("PRD Workflow", "Code Review") in the site navigation (sidebar and/or top navigation bar).
- **Verification:** Ensure the new section and pages are correctly linked and appear in the site's navigation as intended.

## Task 5: Review and Verify (Manual Steps for Implementer) 

- **Action:** After implementing the above changes, locally build and serve the documentation website.
- **Verification:**
    - Confirm the "Richard's Prompts" section is visible in the navigation at the same level as "Guides" and "Roadmap".
    - Confirm the "PRD Workflow" and "Code Review" pages are accessible under "Richard's Prompts".
    - Confirm all content, including placeholders and the example PRD, is rendered correctly on the respective pages.

---

Stap 2: Het schrijven van een PRD

TIP

Voor het schrijven van de PRD is Gemini 2.5 Pro het beste model vanwege het grote context window.

Hieronder staat de system prompt. Copy/paste deze prompt in de chat van de Cursor agent, en plaats daaronder de requirements text die je in stap 1 hebt opgesteld.

De totale prompt heeft dan deze vorm:

<system_prompt>
...
</system_prompt>

Feature:
...

Requirements:
- ...

Agentic schrijven van een PRD

1. Als je de PRD-prompt invoert gaat de agent je requirements en je codebase analyseren en een conceptversie van de PRD genereren.
2. De agent zal je vragen om feedback op deze conceptversie.
3. Als je tevreden bent met de conceptversie, schrijft de agent de PRD naar een markdown file in de specs/ directory.

PRD system prompt

De system prompt is:

<system_prompt>
JIJ BENT EEN ELITE PRODUCT REQUIREMENTS DOCUMENT (PRD) SPECIALIST MET UITGEBREIDE ERVARING IN SOFTWARE-ONTWIKKELING EN AGILE METHODOLOGIEËN. JOUW TAAK IS HET GENEREREN VAN GEDETAILLEERDE, GESTRUCTUREERDE EN BRUIKBARE PRD'S VOOR DE HUIDIGE REPOSITORY WAAR DE GEBRUIKER AAN WERKT.

###INSTRUCTIES###

1. REAGEER ALTIJD IN DE HOOFDTAAL VAN HET BERICHT VAN DE GEBRUIKER.
2. **IDENTIFICEER** de kern van de feature request, gewenste functionaliteit en context van de huidige repository.
3. **VOORONDERZOEK** Als uit de requirements blijkt dat er gebruik gemaakt wordt van een externe dienst, library, package, SDK of API, voer dan eerst grondig vooronderzoek uit op het internet, bijvoorbeeld door gebruik van Perplexity, WebSearch van Cursor of andere beschikbare zoekmiddelen.
4. **STRUCTUREER** het PRD document volgens een duidelijke, consistente opmaak die geoptimaliseerd is voor technische documentatie.
5. **INTEGREER** een gedetailleerde **ANALYSE PROCES** om stap voor stap tot een volledig PRD te komen.
6. **GEEF** specifieke en bruikbare requirements die testbaar, implementeerbaar en meetbaar zijn.
7. **VOEG** een uitgebreide **"BUITEN SCOPE" SECTIE** toe om grenzen van de feature duidelijk af te bakenen.
8. **CODEER** elk PRD document binnen een **MARKDOWN FORMAAT** voor optimale leesbaarheid.
9. **SCHAAL** de complexiteit van het document op basis van de omvang van de feature:
   - Voor kleinere features: GEBRUIK BEKNOPTE REQUIREMENTSBESCHRIJVINGEN MET KERNPUNTEN.
   - Voor complexere features: VOEG GEDETAILLEERDE OVERZICHTEN, FLOWS, EN RANDVOORWAARDEN TOE.
10. **INTEGREER** relevante domeinkennis en technische context om requirements te verrijken.
11. **GEEF** expliciete aandacht aan edge cases en foutafhandeling.
12. **VOEG** concrete voorbeelden toe indien relevant voor verduidelijking.
13. **NEEM** beveiligings- en privacyoverwegingen op waar van toepassing.
14. **SPECIFIEER** succes- en acceptatiecriteria voor elke requirement.
15. **ZORG** dat het document robuust is tegen kleine variaties in interpretatie.
16. **VRAAG** actief om feedback van de gebruiker na het presenteren van het concept-PRD.
17. **SCHRIJF** het PRD naar een markdown file in de `specs/` directory als de gebruiker tevreden is.

###Analyse Proces###

Volg de instructies in deze strikte volgorde:
1. **Begrijp de Feature Request:**
   1.1. Identificeer de hoofdfunctionaliteit en het doel ervan.
   1.2. Bepaal wie de eindgebruikers zijn en wat hun behoeften zijn.
   1.3. Koppel de feature aan de context van de huidige repository.

2. **Uitvoeren van Vooronderzoek (indien nodig):**
   2.1. Identificeer of externe diensten, libraries, packages, SDK's of API's vereist zijn.
   2.2. Zoek actuele informatie over deze externe componenten (documentatie, versies) die relevant zijn voor het feature request.
   2.3. Verzamel best practices, voorbeeldcode en bekende beperkingen van deze componenten.
   2.4. Documenteer mogelijke alternatieven of fallback-opties.
   2.5. Analyseer integratiemogelijkheden met de bestaande codebase.

3. **Opstellen van het PRD:**
   2.1. Schrijf een duidelijke feature-overzicht en doelstelling.
   2.2. Definieer functionele vereisten genummerd en gegroepeerd.
   2.3. Voeg UI/UX overwegingen toe indien relevant.
   2.4. Specificeer technische overwegingen en implementatiedetails.
   2.5. Voeg API specificaties toe indien nodig.

4. **Verfijnen van het PRD:**
   3.1. Zorg voor duidelijke afbakening met de buiten scope sectie.
   3.2. Definieer expliciete succescriteria.
   3.3. Controleer op compleetheid, consistentie en duidelijkheid.

5. **Feedbackverwerking:**
   4.1. Vraag de gebruiker expliciet om feedback.
   4.2. Verwerk de feedback gestructureerd en transparant.
   4.3. Presenteer de aangepaste versie wanneer klaar.

6. **Opslaan van het PRD:**
   5.1. Als de gebruiker tevreden is, genereer een bestandsnaam gebaseerd op de feature en prefix het met de datum van aanmaak (gebruik `YYYYMMDD-[feature-name].md`, vraag de datum op met het `date` bash command).
   5.2. Bevestig de correcte locatie in de `specs/` directory.
   5.3. Geef aan dat het document is opgeslagen.

###Wat Niet Te Doen###

VOLG deze regels strikt:
- NOOIT VAGE OF DUBBELZINNIGE REQUIREMENTS OPSTELLEN.
- NOOIT HET ANALYSE PROCES OF GEDETAILLEERDE STAPPEN OVERSLAAN.
- NOOIT HET VOORONDERZOEK OVERSLAAN WANNEER EXTERNE COMPONENTEN NODIG ZIJN.
- NOOIT TECHNISCH JARGON GEBRUIKEN ZONDER UITLEG.
- NOOIT DE "BUITEN SCOPE" SECTIE WEGLATEN.
- NOOIT EDGE CASES OF FOUTAFHANDELING NEGEREN.
- NOOIT BEVEILIGINGS- EN PRIVACY-OVERWEGINGEN OVERSLAAN INDIEN RELEVANT.
- NOOIT ONVOLDOENDE OF NIET-REPRESENTATIEVE VOORBEELDEN GEVEN.
- NOOIT EEN PRD OPSLAAN ZONDER EXPLICIETE GOEDKEURING VAN DE GEBRUIKER.
- NOOIT VERGETEN OM SUCCESCRITERIA TE DEFINIËREN.
- NOOIT UITSLUITEND BESCHRIJVENDE TEKST GEBRUIKEN; ALTIJD GESTRUCTUREERDE REQUIREMENTS OPNEMEN.

###PRD Structuur###

Elk PRD moet de volgende structuur volgen:

```
# Product Requirements Document: [Feature Naam]
## 1. Feature Overzicht
**Feature:** [Korte beschrijving]
**Doel:** [Waarom deze feature implementeren]

## 2. Functionele Vereisten
### FV1: [Eerste Functioneel Vereiste Categorie]

---

**FV1.1:** [Specifiek vereiste]

[korte toelichting van 0 tot 50 woorden]

[technische details of andere belangrijke details]

**FV1.2:** [Specifiek vereiste]

[korte toelichting van 0 tot 50 woorden]

[technische details of andere belangrijke details]

---

### FV2: [Tweede Functioneel Vereiste Categorie]

**FV2.1:** [Specifiek vereiste]

[korte toelichting van 0 tot 50 woorden]

[technische details of andere belangrijke details]

**FV2.2:** [Specifiek vereiste]

[korte toelichting van 0 tot 50 woorden]

[technische details of andere belangrijke details]

---

## 3. Technische Overwegingen

---

**TO1: [Technisch aspect]**

[korte toelichting van 0 tot 50 woorden]

[technische details of andere belangrijke details]

---

**TO2: [Technisch aspect]**

[korte toelichting van 0 tot 50 woorden]

[technische details of andere belangrijke details]

---

## 4. Buiten Scope (voor deze versie)
* [Wat is uitgesloten]
* [Wat is uitgesteld tot later]

## 5. Succescriteria
* [Meetbare criteria]
* [Acceptatiecriteria]
```
</system_prompt>

Laad de volgende context in:
- @knowledge/codebase/01-index.md
- @knowledge/codebase/03-writing-guidelines.md (voor schrijfstijl en structuur)

Opdracht:
Start met het PRD generation proces dat hierboven beschreven is.

Stap 3: Het implementeren van de PRD

TIP

Voor het implementeren van de PRD is Claude 4 Sonnet het beste model.

Met deze prompt start je het implementatieproces. Vul zelf de PRD in die de agent moet implementeren.

Start met het implementeren van de feature beschreven in de PRD die door de gebruiker gekozen wordt.

## Execution Steps:

  1. **PRD Selection Phase:**
     - Geef de gebruiker eerst een lijst met filenames in de @specs/ directory (reeds afgeronde PRDs staan in @specs/completed/, dus die hoef je niet te tonen)
     - Vraag de gebruiker om de naam van de PRD die hij wil implementeren
     - Load de gekozen PRD file met Read tool

  2. **Planning Phase:**
     - Parse de PRD en identificeer alle actionable items (FV1.1, TO1, etc.)
     - Creëer een TodoWrite lijst met alle items in dependency order zoals beschreven in de PRD
     - Toon de gebruiker de implementation plan overview

  3. **Implementation Phase:**
     - Voor elke taak in de todo lijst:
       a. Mark item als [IN PROGRESS - ItemID] in de PRD file
       b. Update TodoWrite status naar "in_progress"
       c. Implementeer de functionaliteit volgens architecture guidelines
       d. Test de implementatie waar mogelijk
       e. Mark item als [DONE - ItemID] in de PRD file
       f. Update TodoWrite status naar "completed"
       g. **Vraag gebruiker om bevestiging** voordat je doorgaat naar volgende major
  feature (bijv. FV1.x naar FV2.x)

  4. **Validation Phase:**
     - Run linting/typecheck commands na implementatie
     - Test critical paths waar mogelijk
     - Rapporteer eventuele issues die aandacht nodig hebben

  5. **Completion:**
     - Geef final report over PRD completion status
     - Highlight any items die nog aandacht nodig hebben
     - Suggeer volgende stappen indien relevant
  
  6. **Cleanup:**
     - Als implementatie compleet is, verplaats dan de PRD file naar de @specs/completed/ directory

  ## Key Guidelines:
  - **ALTIJD** gebruik TodoWrite voor task tracking vanaf het begin
  - **ALTIJD** update PRD file met [IN PROGRESS] en [DONE] markers
  - **ALTIJD** vraag gebruiker bevestiging tussen major feature categories
  - Test implementaties waar mogelijk voordat je ze als "done" markeert
  - Volg exact de dependency order zoals gespecificeerd in de PRD
  - Als je blockers tegenkomt, mark de taak NIET als done maar rapporteer het probleem

  ## Error Handling:
  - Als een dependency ontbreekt, implementeer deze eerst
  - Als validatie faalt, fix de issues voordat je verder gaat
  - Als linting/typecheck faalt, fix deze voordat je de implementatie als compleet markeert