guides

Workflows

Learn how to use Pinpoint for different types of specifications and workflows.

Common Workflows

Pinpoint adapts to different use cases. Here are the most common workflows and how to optimize for each.

Bug Reproduction

When reporting bugs, clarity is everything. Here's the ideal workflow:

Recording Tips

  1. Start from a clean state — Reset your app to a known state before recording
  2. Show the expected behavior first — If possible, demonstrate what should happen
  3. Then show the bug — Walk through the exact steps to reproduce
  4. End with the error — Capture error messages, console output, network failures

Example PromptDoc Structure

## Bug Report: Login fails with valid credentials
 
### Steps to Reproduce
1. Navigate to /login
2. Enter valid email: test@example.com
3. Enter valid password
4. Click "Sign In"
 
### Expected
User is redirected to dashboard
 
### Actual
Error: "Invalid credentials" (see screenshot)
 
### Environment
- Browser: Chrome 120
- OS: macOS 14.2

Feature Requests

For new features, focus on the what and why:

Recording Tips

  1. Show similar features — If a competitor has it, record that
  2. Demonstrate the user journey — Walk through where the feature fits
  3. Narrate the value — Explain why this matters

Best Practices

  • Keep recordings under 5 minutes
  • Focus on one feature per PromptDoc
  • Include acceptance criteria

Refactoring

When planning refactors, document the before and after:

// Before: Messy component with mixed concerns
function UserProfile() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  // ... 200 lines of mixed logic
}
 
// After: Clean separation
function UserProfile() {
  const { user, loading } = useUser();
  return <ProfileView user={user} loading={loading} />;
}

Recording Tips

  1. Tour the current code — Show what exists today
  2. Highlight pain points — Click on problematic areas
  3. Describe the target state — Narrate the ideal architecture

Developer Onboarding

Create onboarding PromptDocs for new team members:

  1. Record key workflows in your codebase
  2. Annotate architecture decisions
  3. Export as living documentation

These become invaluable references that never go out of date.

Next Steps