prd-converter

Aha Loop PRD Converter

Converts existing PRDs to the prd.json format that Aha Loop uses for autonomous execution.

---

The Job

Take a PRD (markdown file or text) and convert it to prd.json in the scripts/aha-loop directory.

---

Output Format (v2)

{
  "version": 2,
  "prdId": "[PRD-XXX from roadmap or PRD filename]",
  "project": "[Project Name]",
  "branchName": "aha-loop/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "changeLog": [],
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "researchTopics": [
        "Question about technology or best practice",
        "Question about existing patterns"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    }
  ]
}

New v2 Fields Explained

Field	Purpose
version	Schema version (always 2)
prdId	PRD identifier (e.g., PRD-001) for commit message prefixes
changeLog	Array of plan modifications made during execution
researchTopics	Questions to investigate before implementing the story
researchCompleted	Whether research phase is done for this story
learnings	Knowledge gained during implementation (filled by Aha Loop)
implementationNotes	Guidance from research phase for implementation

---

Story Size: The Number One Rule

Each story must be completable in ONE Aha Loop iteration (one context window).

Aha Loop spawns a fresh AI instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.

Right-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list