# Article Builder Update Specification

## Overview

Add an **optional intermediate step** between Step 4 (SEO Questions) and Step 5 (Generate Article) to help users structure their article before generation. This new step will use an AI agent to explain technical concepts from first principles and generate a structured article outline.

## New Step 4.5: Article Structure Planner

### Purpose
Help non-technical writers understand technical article concepts and generate a refined article structure with:
1. [EXPLICACION] - First principles explanation of technical concepts
2. [ESTRUCTURA DE ARTICULO SUGERIDA] - Detailed article structure with technical justifications
3. [SUGERENCIAS] - 10 considerations for refining the structure
4. [PROMPT PARA AI] - Final structured prompt ready for article generation

### Configuration

**Step Number:** 4.5 (will be inserted between current steps 4 and 5)

**Step Config:**
```javascript
{
    id: 'article-structure-planner',
    title: 'Article Structure',
    icon: 'bi-diagram-2',
    description: 'Generate a refined article structure with technical explanations and suggestions.',
    hasPrompt: true,
    promptFile: 'SIMPLIFICATION-EXAMPLES.md',
    dependencies: [
        'articleTitle',
        'articleContext',
        'articleFocus',
        'researchTopic',
        'communityIntel',
        'seoQuestions'
    ],
    requiredSteps: [0, 1, 2, 3, 4],
    placeholders: {
        // No placeholders in the main document body
        // Placeholders are at the end in the [INFORMACION DEL ARTICULO A GENERAR] section
    }
}
```

**Important Notes:**
- This step is **OPTIONAL** - users can skip it
- The prompt file (`SIMPLIFICATION-EXAMPLES.md`) already exists and contains:
  - Instructions for the AI agent
  - Personality definition
  - Example outputs (based on "click-to-load embeds" article)
  - Input fields at the end that need to be populated

### Placeholder Replacement

The placeholders to replace are **at the end** of SIMPLIFICATION-EXAMPLES.md:

```markdown
## [INFORMACION DEL ARTICULO A GENERAR]

### Artículo para hacer este análisis:
[articleTitle]

### Contexto adicional (opcional):
[articleContext]

### Dirección del artículo (Article Focus):
[promptResults[1]]

### Investigación técnica (Research Topic):
[promptResults[2]]

### Inteligencia de comunidad (Community Intelligence):
[promptResults[3]]

### Preguntas SEO (SEO Questions):
[promptResults[4]]
```

### User Workflow
1. User completes Steps 0-4 as normal
2. User navigates to new Step 4.5
3. Prompt is generated with all previous results filled in at the bottom
4. User copies prompt → gives to AI (Claude)
5. AI generates 4 sections: [EXPLICACION], [ESTRUCTURA DE ARTICULO SUGERIDA], [SUGERENCIAS], [PROMPT PARA AI]
6. User pastes AI response into "Prompt Result" textarea
7. **OPTIONAL:** User can skip this step entirely and go directly to Step 5 (Generate Article)

### Result Storage
- Store in `promptResults[5]`
- Mark as completed when result textarea has content
- Completion is **not required** for subsequent steps

---

## Modified Step 5 → Step 6: Generate Article

### Changes Required

**Step renumbering:** Current Step 5 becomes Step 6

**Dependencies remain the same:**
```javascript
requiredSteps: [0, 1, 2, 3, 4]  // Does NOT require step 4.5
```

**Conditional prompt augmentation:**

The existing prompt file `prompts/generate-article.md` should be loaded as normal, but with **conditional logic**:

```javascript
// Pseudocode for logic
let generatedPrompt = loadPromptFile('prompts/generate-article.md');
generatedPrompt = replacePlaceholders(generatedPrompt, placeholders);

// Check if Step 4.5 result exists
if (promptResults[5] && promptResults[5].trim().length > 0) {
    generatedPrompt += `\n\n[SPECIAL USER REQUEST]\nThe user is requesting to follow this specific article structure, so please adhere to that.\n\n${promptResults[5]}`;
}
```

**Key Points:**
- Step 4.5 is **NOT** a required dependency
- Only append if `promptResults[5]` exists and is non-empty
- Append format:
  ```
  [SPECIAL USER REQUEST]
  The user is requesting to follow this specific article structure, so please adhere to that.

  [content of promptResults[5]]
  ```

---

## Step Renumbering

All subsequent steps need to be renumbered:

| Current Step | New Step | Name |
|--------------|----------|------|
| 0 | 0 | User Input |
| 1 | 1 | Article Focus |
| 2 | 2 | Research Topic |
| 3 | 3 | Community Intel |
| 4 | 4 | SEO Questions |
| **NEW** | **4.5 or 5** | **Article Structure** |
| 5 | 6 | Generate Article |
| 6 | 7 | Diagram Designer |
| 7 | 8 | Featured Image |

**Note:** Decide whether to use step number `4.5` or renumber to integers `5, 6, 7, 8, 9`. Recommend integer numbering for simplicity.

---

## Files to Modify

### 1. `prompts-config.js`
- Insert new step configuration at position 5
- Update step numbers for Generate Article (5 → 6), Diagram Designer (6 → 7), Featured Image (7 → 8)
- Ensure dependencies reference correct step numbers

### 2. `index.html`
- Add new tab for Step 5 (Article Structure)
- Add new step-content section with:
  - Prompt display area
  - Copy prompt button
  - Prompt result textarea
  - Paste prompt button
  - Navigation buttons
- Update data-step attributes for all subsequent steps
- Update aria-labels

### 3. `app.js`
- Update step range validation (currently 0-7, will be 0-8)
- Update prompt result input handlers (currently 1-6, will be 1-7)
- **Add special logic** in `renderPrompt()` or `replacePlaceholders()` for Step 6 (Generate Article):
  - Check if `promptResults[5]` exists
  - If yes, append the special user request section
- Update any hardcoded step numbers in comments

### 4. `SIMPLIFICATION-EXAMPLES.md`
- Already exists
- No modifications needed
- Will be used as `promptFile` for new Step 5

### 5. `style.css` (if needed)
- Verify tab layout supports 9 steps (currently shows 8)
- May need responsive adjustments

---

## Implementation Steps

1. **Update `prompts-config.js`**
   - Insert new step 5 configuration
   - Renumber steps 5→6, 6→7, 7→8
   - Update all step references in dependencies

2. **Update `index.html`**
   - Add new tab button for Step 5
   - Add new step-content section for Step 5
   - Renumber all data-step attributes for steps 6, 7, 8
   - Update aria-labels and accessibility

3. **Update `app.js`**
   - Change step range from 0-7 to 0-8
   - Add prompt result input handler for step 5
   - Implement conditional logic for Step 6 (Generate Article) to append `promptResults[5]` if present
   - Update any hardcoded step numbers

4. **Test workflow**
   - Test with Step 5 completed (should append to Generate Article prompt)
   - Test with Step 5 skipped (should work normally)
   - Verify all steps load correctly
   - Verify navigation works
   - Verify localStorage persistence

---

## Edge Cases & Considerations

1. **User skips Step 5 entirely**
   - Should work fine, Generate Article prompt shows normally
   - No error should occur

2. **User clears Step 5 result after filling it**
   - Should not append to Generate Article prompt
   - Check for both existence and non-empty content

3. **Placeholder replacement in SIMPLIFICATION-EXAMPLES.md**
   - Most of the document is static (examples)
   - Only replace placeholders in the final section under `[INFORMACION DEL ARTICULO A GENERAR]`
   - Need special handling since placeholders aren't in the standard format

4. **Step number vs Step ID**
   - Internal references use step number (0-8)
   - Display labels show "Step 0", "Step 1", etc.
   - Consider whether Step 5 displays as "Step 5" or "Step 4.5" in UI

---

## Success Criteria

- [ ] New Step 5 (Article Structure) appears in tab navigation
- [ ] Step 5 prompt loads with all 6 previous inputs filled in at the bottom
- [ ] User can copy Step 5 prompt and paste result
- [ ] Step 5 completion is tracked but not required
- [ ] User can skip Step 5 and go directly to Step 6 (Generate Article)
- [ ] When Step 5 result exists, it's appended to Generate Article prompt
- [ ] When Step 5 result is empty, Generate Article prompt works normally
- [ ] All subsequent steps (Diagram Designer, Featured Image) work correctly
- [ ] localStorage persists Step 5 data correctly
- [ ] Navigation between all 9 steps works smoothly
