ralph-loop

name	ralph-loop
description	Autonomous PRD implementation with 8-phase quality pipeline. Keeps going until done.

/ralph-loop [prd-file] [--max N] [--resume]

Autonomous loop that implements PRD items through an 8-phase quality pipeline (plan → structure → implementation → refactoring → deduplication → review → testing → evaluation).

No arguments? Describe this skill and stop. Do not execute.

Craft Standards (CORE PRINCIPLE)

Every line of code must be worthy of a master craftsperson's pride.

Ralph exists to produce code that looks like it was written by a skilled human engineer, not generated by AI. This is the north star for every phase.

AI Antipatterns to REJECT at Every Phase

Antipattern	What It Looks Like	Why It's Wrong
Over-abstraction	Factories, builders, wrappers used once	Abstraction without justification
Defensive paranoia	Null checks where null is impossible	Implies misunderstanding of your own code
Reimplementing stdlib	Custom utilities when libraries exist	Arrogance or ignorance
Comment spam	// increment counter above i++	Insulting the reader
Speculative features	Config options nobody asked for	Solving imaginary problems
Enterprise patterns	AbstractFactoryBean for a helper	Cargo-culting
Wrapper classes	UserWrapper around User	Complexity without value

Human Craft Standard

At every phase, code must have:

• Clarity - Reads like well-written prose
• Focus - Each function does one thing perfectly
• Intent - Names reveal purpose without comments
• Simplicity - Clearly took effort to achieve
• Justification - Every line earns its place

Test at every phase: Would a senior engineer mass-delete this in review? If yes, don't write it.

---

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"ralph-loop","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

The 5 Stages

PER PRD ITEM (Design → Build → Refine → Review → Verify):
  Design   📝  plan + structure → Analyze requirements, design types
  Build    🛠️  implement              → Write code
  Refine   🧹  refactor + dedupe      → Refine structurally, consolidate
  Review   🔍  gemini + qodana + security → External review, fix ALL issues
  Verify   🧪  tests + docs           → Write tests, document APIs
  → Mark item complete, loop to next

POST-LOOP (after ALL items complete):
  Review   🔒  adversarial security audit
  Verify   🚀  production readiness checks

Loop Behavior

while PRD has incomplete items AND iteration < max:
    item = next_incomplete_item()

    run_phases_1_through_8(item)

    mark_item_complete_in_PRD()
    commit()

    # MANDATORY: Continue to next item
    remaining = count_incomplete_items()
    if remaining > 0:
        print(f"{remaining} items remain. Starting next...")
        continue  # DO NOT STOP

run_phases_9_and_10()  # Post-loop validation
generate_skill_usage_report()

Stopping Rules (ONLY valid exits)

1. All PRD items [x] → Run post-loop → Exit
2. Max iterations (50) → Report status → Exit
3. Idle (3 iterations, 0 commits) → Exit
4. Checkpoint trigger → Run /save-progress → Exit for handoff

Checkpoint Triggers

Run /save-progress and exit cleanly when ANY of these occur:

• 3 PRD items completed this session
• 10 iterations reached
• Any file read twice (sign of context issues)

Invalid Stops (bugs)

• Stopping when incomplete items remain
• Asking "should I continue?"
• Waiting for user input between items
• Reporting "complete" before last item done

Arguments

Arg	Description
prd-file	Path to PRD (default: PRD.md)
--max N	Max iterations (default: 50)
--resume	Continue from last checkpoint

PRD Format

- [ ] Item 1: Description
- [ ] Item 2: Description
- [x] Item 3: Description (COMPLETE)

Phase Tools

Phase	Tool/Skill
gemini-review	mcp__gemini-reviewer__gemini_review
qodana-review	mcp__qodana__qodana_scan or qodana CLI
write-tests	npm test / pytest / equivalent

Auto-Invoke Rules (MANDATORY)

During implement phase, detect context and invoke domain skills:

By File Type

Pattern	Invoke	Why
*.tsx, *.jsx, *.vue	/components, /visual, /usability	UI components
*.css, *.scss, *.styled.*	/design	Styling
*.ts (non-UI)	/typescript	TypeScript patterns
React files	/react-state	React mental models

By PRD Keywords

Keywords	Invoke	Why
form, input, validation	/mobile, /usability	Forms expertise
animation, transition, motion	/motion	Meaningful motion
mobile, responsive, touch	/mobile, /interaction	Mobile patterns
auth, login, password, session	/security-mindset, /owasp	Security
test, spec	/react-test	Testing patterns
data visualization, chart, graph	/d3	D3/viz patterns

By Architecture

Context	Invoke	Why
System design, new architecture	/resilience, /failure	Resilience, failure modes
Major refactoring	/failure, /resilience	Learn from failures
Design system work	/tokens	Token governance
Typography decisions	/typography	Type hierarchy

Output when invoking: "🎨 UI detected → Invoking /components, /visual, /usability"

Required Docstring Formats (MUST USE)

JavaScript/TypeScript - JSDoc

/**
 * Authenticates a user with email and password.
 *
 * @param credentials - User login credentials
 * @param credentials.email - User's email address
 * @param credentials.password - User's password
 * @returns Promise resolving to auth tokens
 * @throws {AuthError} If credentials are invalid
 *
 * @example
 * ```typescript
 * const tokens = await authenticate({
 *   email: '[e-mail]',
 *   password: 'secret123'
 * });
 * ```
 */
export async function authenticate(credentials: Credentials): Promise<Tokens>

Python - Google-style Docstrings

def authenticate(credentials: Credentials) -> Tokens:
    """Authenticates a user with email and password.

    Args:
        credentials: User login credentials with email and password.

    Returns:
        Authentication tokens for the session.

    Raises:
        AuthError: If credentials are invalid.

    Example:
        >>> tokens = authenticate(Credentials(
        ...     email="[e-mail]",
        ...     password="secret123"
        ... ))
    """

Java - Javadoc

/**
 * Authenticates a user with email and password.
 *
 * @param credentials the user's login credentials
 * @return authentication tokens for the session
 * @throws AuthException if credentials are invalid
 */
public Tokens authenticate(Credentials credentials) throws AuthException

Documentation Gate (MUST PASS)

Before marking ANY PRD item complete, verify ALL:

• All public functions have docstrings (format above)
• All public classes have class-level docstrings
• All parameters documented with types
• All return values documented
• All exceptions/errors documented
• At least one @example for complex functions
• README updated if new module/feature

If ANY checkbox is unchecked → DO NOT mark item complete. Add docs first.

Quality Gates (MUST ALL PASS)

Do NOT mark a PRD item [x] until ALL gates pass:

Gate	Check	Required
Build	npm run build or equivalent	0 errors
Tests	npm test or equivalent	100% pass
Lint	npm run lint or equivalent	0 errors
Types	tsc --noEmit (if TS)	0 errors
Docs	Documentation gate above	All checked
Gemini	Phase 5 gemini-review	0 CRITICAL/HIGH
Qodana	Phase 6 qodana-review	0 CRITICAL/HIGH

Enforcement:

if any_gate_fails:
    DO NOT mark item complete
    Fix the failing gate
    Re-run the gate
    Loop until pass

NEVER skip a gate. NEVER mark complete with failures.

Output

Per item:

Item N: [name]
  📝 plan → ✓
  🏗️ structure → ✓
  🛠️ implement → ✓
  🧹 refactor-fix → ✓
  🔍 gemini-review → 3 issues fixed
  📊 qodana-review → 1 issue fixed
  🧪 write-tests → 5 passed
  📚 generate-docs → ✓
  ✅ COMPLETE

2 items remain. Starting next...

Final:

Ralph Loop Complete ✓
Items: 4/4 complete
Post-loop: security ✓, production-readiness ✓
Report: .claude/skill-usage-report.html