Advanced Context

my-portfolio/
├── docs/
│   ├── project-goals.md
│   ├── design-philosophy.md
│   ├── progress-log.md
│   └── style-guide.md
├── planning/
│   ├── user-research.md
│   ├── content-strategy.md
│   └── technical-requirements.md
├── assets/
│   ├── images/
│   └── fonts/
├── styles/
│   ├── base.css (reset, typography)
│   ├── layout.css (grid, flexbox)
│   ├── components.css (cards, buttons)
│   └── utilities.css (spacing, colors)
├── index.html
├── about.html
├── portfolio.html
└── contact.html

Advanced prompt example:

"Based on my design-philosophy.md and the component patterns established in styles/components.css, help me create a new testimonial section for portfolio.html. The design should follow the card-based approach from my existing project showcases while incorporating the color system defined in my style-guide.md."

# Design System Context

## Color Tokens
- primary-100: #e3f2fd (light blue background)
- primary-500: #2196f3 (main blue)
- primary-900: #0d47a1 (dark blue text)

## Spacing Scale
- xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, xxl: 48px

## Component Patterns
- Cards: 8px border-radius, md padding, subtle shadow
- Buttons: sm border-radius, md padding, transition: 0.2s
- Forms: lg spacing between fields, focus rings required

## Typography Scale
- Display: 3rem/1.2, Heading: 2rem/1.3, Body: 1rem/1.6, Caption: 0.875rem/1.4

🚨 Red Flags

• Agent suggests solutions that ignore your constraints
• Code doesn't match your established patterns
• Suggestions break existing functionality
• Agent asks for clarification on previously established decisions

⚠️ Warning Signs

• Generic responses that could apply to any project
• Solutions that don't reference your existing files
• Recommendations that conflict with your design philosophy
• Code that doesn't follow your naming conventions

Step 1: Clarify Context

"I think there's a misunderstanding. Please re-read my project-goals.md and design-philosophy.md files, then review my specific constraints: [list constraints]. My current challenge is [restate clearly]."

Step 2: Provide Specific Examples

"For example, in my existing portfolio section, I use CSS Grid with these specific properties: [show exact code]. I need the new section to follow this same pattern but for [specific content]."

Step 3: Reset and Restart

"Let's start over. I'm working on [project] with these requirements: [specific list]. Please suggest an approach that fits these constraints and aligns with my established patterns in [specific files]."

❌ Mistake: Assuming agent remembers previous conversations

Problem: "Continue from where we left off yesterday"

Solution: Always reference your progress-log.md and provide current context

❌ Mistake: Vague constraint communication

Problem: "Make it accessible and responsive"

Solution: "Ensure WCAG AA compliance (4.5:1 contrast) and mobile-first responsive design with breakpoints at 768px and 1024px"

❌ Mistake: Not providing file structure context

Problem: "Add styles to make this look better"

Solution: "Add styles to styles/components.css following the button patterns established in my style-guide.md"

POETRY PROJECT CONTEXT TEMPLATE:

"I'm implementing my poetry interpretation project for [Poem Title].

CREATIVE CONTEXT:
- Read poem-analysis.md for themes and mood analysis
- Review visual-concept.md for design direction
- The poem's [specific aspect] should drive [specific technical decision]

TECHNICAL CONTEXT:
- Follow design-philosophy.md for color/typography system
- Reference style-guide.md for CSS organization patterns
- Constraints: HTML/CSS only, WCAG AA, mobile-first responsive

CURRENT CHALLENGE:
I need to [specific technical goal] while maintaining [specific artistic element].
The [poem aspect] should be reflected through [design technique].

INTEGRATION REQUIREMENT:
The solution must work with my existing [file/component] and follow the
patterns established in [specific file reference]."

## Iteration Log Example

### Iteration 1: Initial Layout
**Artistic Goal:** Reflect poem's structured verses
**Technical Solution:** CSS Grid with defined rows for each stanza
**Result:** Too rigid, doesn't capture poem's emotional flow
**Learning:** Strict structure conflicts with emotional expression

### Iteration 2: Flowing Layout
**Artistic Goal:** Create emotional rhythm through spacing
**Technical Solution:** Flexbox with variable margins based on stanza mood
**Context for Agent:** "Based on iteration 1 feedback in my progress-log.md,
help me implement flexible spacing that reflects emotional intensity"

Advanced accessibility prompt:

"My poem interpretation uses dark backgrounds and creative typography to reflect melancholy themes. Help me maintain this artistic vision while ensuring screen reader compatibility and 4.5:1 contrast ratios. Reference my visual-concept.md for the specific mood I'm trying to create."

Stage 1: Foundation Context

Goal: Establish basic project understanding

Files: project-goals.md, basic design-philosophy.md

Prompts: Simple, focused requests for core functionality

Stage 2: Pattern Context

Goal: Develop consistent patterns and conventions

Files: style-guide.md, component examples, progress-log.md

Prompts: Reference existing patterns, ask for consistency

Stage 3: System Context

Goal: Create cohesive design system understanding

Files: design-system.md, multiple component files

Prompts: Complex coordination across multiple files and patterns

Stage 4: Mastery Context

Goal: Sophisticated optimization and refinement

Files: Complete documentation ecosystem

Prompts: Advanced optimization, accessibility, performance