How Documentation Helped Me Rebuild My Website with AI

I recently transformed my personal website from a Vue SPA into a static Astro website. I also added a local Payload CMS, moved my portfolio content into it, and brought my existing DEV articles into the website.

The work happened over two focused days. AI helped me move quickly, but the speed did not come from one large prompt. It came from a strict documentation workflow I call AI Task Planning Architecture.

This workflow helps AI agents maintain context, resume interrupted tasks, and execute implementations systematically. The website transformation was a good test of it.

The Website Transformation

The old website used Vue, Vue Router, and Pinia for content that was mostly static. The browser was doing work that could be completed during the build.

The new website uses Astro for static pages, React for reusable components, Tailwind CSS for styling, and Payload CMS for content management. Payload exports published content into a typed snapshot, and Astro uses that snapshot to generate the website. The deployed website does not need a running CMS or database.

During this transformation, I:

• migrated the website from Vue to Astro and React;
• added a local CMS and static content pipeline;
• moved 20 projects, 6 experiences, and 26 technologies into the CMS;
• migrated 7 blog posts from DEV;
• preserved the PWA, SEO, responsive design, and accessibility behavior;
• removed unnecessary client-side state and routing.

These are useful productivity outputs, but the reusable development process behind them is more important.

AI Task Planning Architecture

Every task gets a dated folder with four documents:

plans/
  └── [issue-name]-[date]/
      ├── problem.md
      ├── investigation.md
      ├── solution.md
      └── retro.md

The files are not created only to explain finished code. They guide the complete task from the first prompt to the final review.

The workflow runs in this order:

1. Initialization: The agent reads AGENTS.md to load the project and workflow rules.
2. Prompt intake: The user provides the task or problem.
3. Setup: The agent creates plans/[issue-name]-[YYYY-MM-DD]/.
4. Problem definition: The agent creates problem.md and records any missing context through Q&A.
5. Investigation: The agent studies the repository, finds the root causes, and creates investigation.md.
6. Solution planning: The agent selects the best approach and creates solution.md.
7. Implementation: The agent applies the documented solution.
8. Retrospective: After successful implementation, the agent creates retro.md.

AGENTS.md + user prompt
          |
          v
 plans/[issue]-[date]/
          |
          v
     problem.md
          |
          v
  investigation.md
          |
          v
     solution.md
          |
          v
   implementation
          |
          v
       retro.md

Each file removes a different type of uncertainty.

problem.md: Preserve the Request

The problem document includes the user's exact initial prompt. It then gives a lean and direct explanation of the issue.

If the agent is missing important context, it asks questions and appends the answers to the same file. This is important because decisions should not disappear inside a chat history.

The document becomes the task contract. A new agent can read it later and understand what the user actually requested without receiving a rewritten summary.

investigation.md: Understand Before Changing

The investigation document lists the root causes and affected components. It uses bullet points with exact file paths, line numbers, and links between related logic. Relevant git history is included when it explains why the current code exists.

This phase is based on repository evidence, not assumptions. The agent does not write code yet.

This restriction prevents a common AI problem: finding one visible symptom and immediately generating a patch. Investigation forces the agent to understand the data flow, existing patterns, and possible side effects first.

solution.md: Decide Before Implementing

The solution document defines the exact fix. It covers implementation logic, architectural changes, best practices, and the files that need to change.

When multiple approaches are possible, the agent lists them briefly and strictly justifies the selected one. This makes the tradeoff visible before code exists.

For example, querying Payload directly from the deployed website looked simpler during the CMS work. The investigation showed that the website was statically deployed and the CMS was local. The selected solution used a static export pipeline instead, keeping production independent from the CMS.

Implementation must follow solution.md. If the plan is wrong, the plan should be corrected instead of silently changing direction while coding.

retro.md: Record What Actually Happened

The retrospective is created only after successful implementation. It briefly summarizes the problem, investigation, and applied solution.

It also critiques the implementation complexity, records blockers, and recommends future refactoring or project improvements. It describes the real result rather than copying the expected result from solution.md.

This gives the next agent useful project history. It can see which alternatives failed, which decisions worked, and which technical debt was intentionally left for later.

The Restrictions Make It Useful

The value does not come from having four Markdown files. It comes from following the restrictions around them:

• read AGENTS.md before starting;
• create one dated plan folder for every task;
• preserve the exact user prompt;
• ask for missing context and record the answers;
• do not write code before problem.md, investigation.md, and solution.md exist;
• link investigation findings to exact files and logic;
• implement strictly from the selected solution;
• keep every document lean, direct, and free of unnecessary language;
• write the retrospective only after the implementation succeeds.

These restrictions reduce random decisions. They also make tasks resumable. If an agent stops after investigation, another agent can continue from the same folder without repeating the entire conversation or repository analysis.

Why Linting and Validation Still Matter

Documentation explains intent, but it cannot enforce intent. AI can read a naming rule and still forget it. It can use an old API, leave an unused variable, or create code that looks correct but does not build.

I use strict ESLint, TypeScript, Prettier, content validation, and production builds as executable guardrails. ESLint enforces rules such as arrow callbacks, const usage, strict equality, curly braces, unused variables, and recommended React, React Hooks, and Astro behavior. TypeScript protects contracts between content and components. Content validation rejects invalid CMS exports. The production build checks that the complete static website can be generated.

solution.md
    |
    v
implementation ---> ESLint + TypeScript + validation + build
    ^                              |
    |-------- fix failures --------|
                                   |
                                   v
                        verify real behavior
                                   |
                                   v
                               retro.md

Documentation defines what the agent should do. Validation tools reject what it must not do.

This feedback improves productivity because AI can fix small, deterministic failures by itself. Human review can then focus on architecture, behavior, and product decisions instead of formatting or preventable code-quality problems.

What I Learned

AI can write code quickly, but fast code generation is not the same as fast development. Real productivity means reaching the correct result with fewer regressions, less repeated investigation, and enough context for the next task.

My workflow is simple: preserve the prompt, investigate the system, document the decision, implement the plan, validate the real result, and record what happened.

The website transformation is one output of this method. The more valuable output is a development process that keeps its context and becomes stronger after every task.