Picture this: You’re three weeks into development. The designer shows you a mockup. You stare at it, confused.
“Wait,” you say, “I thought we were building this for enterprise customers.”
“No,” the designer replies, “we’re targeting solo developers. That’s why everything is stripped down.”
Meanwhile, product walks in: “Why isn’t this multi-tenant? We need team workspaces.”
Everyone built what they thought the product should be. Nobody aligned on what it actually is. Now you’re three weeks in and realizing you’ve built three different visions of the same app.
This is the most expensive mistake in software development. Not bugs. Not technical debt. Misalignment. When teams don’t share the same understanding of vision, goals, and stakeholders, they build the wrong thing—efficiently.
The solution? Canvas Thinking. Six lightweight files that answer the strategic questions before you write a single line of code.
The Problem: Building in Different Directions
Here’s how misalignment happens:
Product reads the TRD and thinks: “We’re building for enterprise teams who need collaboration and compliance.”
Design reads the same TRD and thinks: “We’re building for solo developers who need speed and simplicity.”
Engineering looks at technical constraints and thinks: “We’re building an API-first platform that anyone can integrate.”
All three are building based on assumptions they never confirmed with each other. The TRD defined what to build, but it didn’t clarify the strategic context: Who is this for? What problem are we really solving? What does success look like? What are we uncertain about?
That’s where the canvas comes in.
What Is a Canvas?
A canvas is a structured way to capture strategic context in six simple files:
- vision.md — Where are we going in 12 months?
- goals.md — What are we measuring? (SMART objectives)
- stakeholders.md — Who benefits? Who buys? Who builds?
- questions.md — What don’t we know? What’s uncertain?
- ideas.md — Brainstorming and inspiration
- notes.md — Observations and learnings
Each file is 10-30 lines. Total time to fill: 30 minutes. Total misalignment prevented: weeks of wasted work.
The canvas sits between your TRD and your plan. TRD says what you’re building. Canvas says why, for whom, and with what unknowns. Then you extract a plan.
##Deep Dive: The Six Canvas Files
1. vision.md — Where Are We Going?
Vision answers the 12-month question: If this project succeeds, what will be true that isn’t true now?
Bad vision (too vague):
# Vision
Build a great product that users love and that makes money.
Good vision (specific, testable):
# Vision
## Purpose
Become the default authentication provider for indie SaaS developers who want GDPR-compliant auth without managing OAuth infrastructure.
## Success Signals
- 500 active developers using the service
- 10k authentication requests/day
- Featured in "awesome-saas-tools" lists
- NPS >50
## Non-Goals
- Not targeting enterprise (no SSO, no compliance certifications)
- Not building a user management dashboard
- Not competing with Auth0/Okta on features
Notice: specific user segment, measurable outcomes, explicit non-goals. This prevents scope creep and keeps everyone aligned on target.
2. goals.md — What Are We Measuring?
Goals are SMART objectives with timeframes. They answer: How do we know if we’re succeeding?
Bad goals (vague, unmeasurable):
# Goals
- Build a fast auth system
- Get users
- Make it secure
Good goals (SMART: Specific, Measurable, Achievable, Relevant, Time-bound):
# Goals
## Short-term (4 weeks)
- Complete email/password signup flow with <300ms response time (p95)
- Pass OWASP security checklist for authentication
- Deploy to production with 99.9% uptime SLA
## Mid-term (12 weeks)
- Reach 100 active developers using the service
- Support 5k authentication requests/day with <1% error rate
- Publish API documentation and 3 integration tutorials
## Long-term (6 months)
- Achieve 500 active developers
- Generate $2k MRR from premium tier
- Establish partnerships with 3 indie SaaS communities
Now everyone knows what success looks like at every stage. No guessing. No “I thought we were aiming for…“
3. stakeholders.md — Who Cares About This?
Stakeholders answers: Who benefits? Who pays? Who builds? Who approves?
This is the most overlooked file—and the most critical. Misunderstanding stakeholders means building for the wrong audience.
Example:
# Stakeholders
## Primary Users
- Indie SaaS developers (1-3 person teams)
- Technical founders without security expertise
- Developers migrating from Firebase Auth
Expectations: Fast setup (<30 mins), clear docs, no surprises in pricing
## Secondary Users
- End users logging into apps built with our service
- They don't know we exist (white-label)
## Decision Makers
- Technical founders (choose auth provider)
- Evaluate on: ease of integration, compliance, cost
## Internal Team
- Engineering: 2 developers (backend focus)
- Product: Founder (part-time)
- Support: Initially founder, later contractor
## External Constraints
- Must satisfy GDPR requirements (legal)
- Must integrate with Stripe (payments)
Now design knows not to build complex admin dashboards (users are technical). Product knows pricing must be transparent (founders evaluate on cost). Engineering knows to prioritize docs (fast setup is key).
4. questions.md — What Don’t We Know?
This is the most powerful file in the canvas. It captures uncertainty—the things you need to research, test, or decide before you can confidently build.
Example:
# Open Questions
## User Behavior
- Q1: Do developers prefer OAuth (Google/GitHub) or email/password for their end users?
- Research: Survey 50 indie devs, analyze auth patterns in popular tools
- Q2: Will users accept 24-hour session expiry, or do they expect "remember me" for 30 days?
- Research: Competitive analysis, user testing
## Technical
- Q3: Can we handle 10k concurrent sessions on a single $50/mo server, or do we need load balancing?
- Research: Load testing, benchmark Postgres connection pooling
- Q4: Should JWT tokens be stored in localStorage (XSS risk) or httpOnly cookies (CSRF risk)?
- Decision: Evaluate tradeoffs, pick one, document in ADR
## Business
- Q5: What pricing model works for indie devs—pay-per-user or flat monthly fee?
- Research: Test pricing page with 3 options, track conversion rates
Every question becomes a research task or decision point. When someone asks “Have we decided XYZ?” you check this file. If it’s not there, add it.
5. ideas.md — Brainstorm Without Committing
Ideas is your parking lot for “wouldn’t it be cool if…” thoughts. It prevents derailment without killing creativity.
Example:
# Ideas
## Features (Not Committed)
- Magic link login (passwordless)
- Biometric authentication (Face ID/Touch ID)
- Social login beyond Google/GitHub (Twitter, LinkedIn)
- Audit log for all auth events
## Growth Tactics
- Launch on Product Hunt with "GDPR-compliant auth in 30 mins" angle
- Write case studies with early adopters
- Build Wordpress plugin for indie bloggers
## Future Exploration
- White-label admin dashboard (charge premium tier)
- Zapier integration for automation workflows
When someone says “we should add Twitter login!” you respond: “Great idea—let’s add it to ideas.md and revisit in Phase 2.” Now you’ve acknowledged the idea without committing to scope creep.
6. notes.md — Capture Learnings
Notes is for observations, insights, and context that doesn’t fit elsewhere. It grows as you learn.
Example:
# Notes
## 2026-02-15: User Research Insights
- Interviewed 12 indie developers. 9/12 prefer OAuth over email/password for their users.
- Main concern: "I don't want to store passwords and deal with breaches."
- Pricing: Prefer flat monthly fee over per-user pricing (predictable costs).
## 2026-02-20: Technical Discovery
- Postgres connection pooling with pgBouncer handles 5k concurrent sessions easily.
- JWT in httpOnly cookies + SameSite=Strict prevents CSRF without XSS risk.
- Decided to use RS256 signing (ADR-003).
## 2026-03-01: Competitive Analysis
- Auth0: Too expensive for indie devs ($23/mo minimum).
- Firebase Auth: Easy but vendor lock-in concerns.
- Supabase Auth: Popular but lacks advanced RBAC.
- Opportunity: Position as "GDPR-first" alternative.
Six months later, someone asks “Why did we choose RS256 over HS256?” You check notes, see the date, link to the ADR. Context preserved.
How Canvas Prevents Misalignment (A Real Example)
Let’s say you’re building a project management tool. Here’s how canvas prevents disaster:
Without Canvas:
- Designer builds a minimal UI for solo users
- Engineer builds multi-tenant architecture for teams
- Product pitches enterprise features to investors
- Three weeks in: “Wait, who is this even for?”
With Canvas: You fill stakeholders.md first and discover:
- Primary users: Small teams (5-10 people), not solo users, not enterprise
- Decision makers: Team leads who evaluate on collaboration features
- Key constraint: Must integrate with Slack and Asana
Now:
- Designer knows to optimize for team workflows, not solo use
- Engineer knows multi-tenant is correct architecture
- Product knows to emphasize collaboration in marketing, not enterprise compliance
Everyone builds the same product because they’re working from the same canvas.
How to Fill the Canvas (30-Minute Exercise)
Step 1: Start with vision.md (10 minutes)
Answer these prompts:
- If this project succeeds in 12 months, what will be true?
- Who will use it?
- What will they be able to do that they can’t now?
- What are we NOT trying to do?
Step 2: Draft goals.md (10 minutes)
Pick 3-5 measurable outcomes for each timeframe (short/mid/long-term):
- Use numbers: “100 users” not “lots of users”
- Add deadlines: “by week 12” not “soon”
- Make them testable: “95% uptime” not “reliable”
Step 3: Map stakeholders.md (5 minutes)
List everyone who touches the project:
- Who uses it?
- Who pays for it?
- Who approves decisions?
- What do they expect?
Step 4: Capture questions.md (5 minutes)
Write down everything you’re uncertain about:
- User behavior you need to research
- Technical decisions you haven’t made
- Business assumptions you need to test
Ideas and notes can start empty—they fill as you go.
When to Revisit the Canvas
Canvas isn’t write-once-and-forget. Revisit it when:
- Big decisions happen: Update notes with the decision and why
- Scope changes: Move items from ideas to plan, update vision if needed
- User research completes: Answer questions, adjust goals based on findings
- Milestones hit: Check if success signals from vision.md are true
Canvas is a living document. Keep it alive.
Why This Matters More Than Code Quality
You can write perfect code for the wrong product. You can’t ship a valuable product if your team is building in different directions.
Canvas alignment prevents:
- Wasted sprints building the wrong features
- Design/engineering conflicts (“This isn’t what I designed!”)
- Stakeholder surprises (“I thought we were targeting enterprise?”)
- Feature bloat (everything goes in ideas.md first)
Canvas alignment enables:
- Faster decisions (check vision for north star)
- Clear prioritization (goals define success)
- Confident planning (questions surface before they derail you)
It’s 30 minutes of alignment that saves weeks of rework.
Try It With Your Team
Pick your current project. Block 30 minutes with your team. Fill the canvas together:
- vision.md: Where are we going? What’s out of scope?
- goals.md: How do we measure success at 4 weeks, 12 weeks, 6 months?
- stakeholders.md: Who are we building for? What do they expect?
- questions.md: What don’t we know yet?
Then ask: “Did we just discover any misalignment?”
Chances are, you’ll find at least one thing where teammates had different assumptions. Fix it now, before it becomes three weeks of wasted work.
Coming in Post 4: From Backlog to Done: Tracking Real Progress — Learn how to translate canvas + plan into actionable backlog items with acceptance criteria, and how status.md keeps you honest about what’s actually getting done.
Keywords: project canvas, strategic alignment, team collaboration, project vision, stakeholder mapping, requirements alignment