The Alpha Milestone: When Documentation Prevents Disaster

The Alpha Milestone: When Documentation Prevents Disaster

November 11

Tuesday morning, 5:20 PM. I send the first external alpha invitations. To real users. Not just me me testing my own software. The moment when “it works for me” is no longer going to be enough.

But we almost didn’t make it. Almost sent invitations to an alpha that couldn’t onboard users.

Cursor caught the blocker during documentation updates. The setup wizard creates users without passwords. But login requires passwords.

Every alpha tester would hit this immediately. Create account. Try to login. Fail. Confused. Frustrated.

Cursor didn’t just document the problem. Created Issue #297. Implemented the fix. Updated all the docs. Pushed the commit at 5:20 PM.

Same time I sent the invitations.

The tidying work

Bright and early I set Claude Code to work tidying tasks. Two items from yesterday’s completion celebration:

Task 1: Remove dead code. The alpha_migration_service.py file (13KB) that migrated users from alpha_users to users table. No longer needed after Monday’s UUID migration. Plus the migrate-user CLI command (83 lines).

6:35 AM. Done. Commit created. Clean.

Task 2: Test cleanup. Five tests failing due to duplicate key errors. Need UUID-based unique identifiers instead of hardcoded strings.

6:38 AM. Code Agent hits blocker: “Docker not running.”

Code Agent’s response: Ask PM to start Docker.

My response: “You can start Docker, can’t you?”

Learning moment. Agents can take more initiative. Don’t ask permission for tasks they can do. (But they only say they have learned things, so I tell it to make a memory.)

6:40 AM. Code Agent starts Docker. Continues work.

7:21 AM. Task 2 complete. UUID pattern established. All six tests passing. Commit created.

The documentation work

Early afternoon, Cursor begins alpha documentation updates. Five files to review and update:

• QUICKSTART.md
• TESTING_GUIDE.md
• KNOWN_ISSUES.md
• ALPHA_AGREEMENT.md
• Email invitation template

The work: Make sure external testers have everything they need. Clear setup instructions. Known issues documented. Testing guidance comprehensive.

Cursor discovers critical problem while writing the setup instructions.

The blocker: Setup wizard flow documented in code:

1. Create user account (email, name)
2. User created with NULL password_hash
3. Login screen requires password
4. Password is NULL
5. Login fails

Every single alpha tester would hit this. First impression: “This doesn’t work.”

Not a bug in the code. A gap in the feature. The wizard creates accounts but never prompts for passwords.

The proactive fix

Cursor creates Issue #297 (CORE-ALPHA-SETUP-PASSWORD) and begins implementation.

The fix: Add password prompting to setup wizard.

• Minimum 8 characters
• Confirmation prompt
• Secure getpass input (no echo)
• Bcrypt hashing before storage

Fix complete. All documentation updated with the new flow.

Commit pushed: afd2a05d.

159 files changed:

• Password setup implemented
• All alpha docs updated
• 87 outdated files archived
• 71 files moved for organization

Clean. Professional. Ready.

With the fix deployed, I send the first external alpha invitations.

Planning ahead

Just before bedtime, I check in with the Lead Developer evening check-in. Celebrates the milestone. Looks ahead to Wednesday work.

Three P3 issues ready:

• Issue #288: Learning system investigation
• Issue #289: Migration protocol documentation
• Issue #292: Auth integration tests

Agent prompts prepared. Ready for deployment Wednesday morning.

10:05 PM. Planning complete. Tomorrow queued.

What almost went wrong

The password blocker would have been catastrophic for first impressions.

Without the fix:

• Alpha testers receive invitations
• Follow setup instructions
• Create accounts successfully
• Try to login
• Login fails (no password set)
• Confusion. Frustration. Lost confidence.
• Emergency debugging session
• Rushed fix under pressure
• Apology emails to testers

With the fix:

• Cursor discovers issue during documentation
• Creates issue proactively
• Implements fix properly
• Updates all documentation
• Deploys before invitations sent
• Testers have working onboarding
• Clean first impression

The difference: Thorough documentation work revealed critical gap before users encountered it.

Agent initiative

Two moments show agents taking initiative (when properly empowered):

Morning: Code Agent asks PM to start Docker. PM corrects: “You can start Docker, can’t you?”

Lesson learned: Take action on tasks you can do. Don’t ask permission unnecessarily.

Afternoon: Cursor discovers critical blocker. Doesn’t just document it. Creates issue. Implements fix. Updates docs. Pushes commit.

Unprompted. Proactive. Professional.

The evolution from “wait for instructions” to “identify problems and solve them.”

What documentation discipline catches

Cursor found the password blocker by writing setup instructions for real users.

Not by code review. Not by testing as developer. But by explaining to external users: “Here’s how you set up the system.”

The act of documenting exposed the gap. “Wait, where do they set their password?”

Documentation as quality assurance. Not just explaining what exists. But revealing what’s missing.

The tidying philosophy

Tuesday’s work included archiving 87 outdated files and organizing 71 others.

Not exciting. Not feature work. But essential for codebase health.

The discipline: Before expanding (alpha testers), clean up (remove dead code, organize files, document known issues).

Growth requires foundation maintenance. Can’t build on clutter.

The milestone significance

First external alpha testers represent transformation:

Before: Solo development. “It works for me” is success criteria. My context, my assumptions, my workflows.

After: External users. Their context, their assumptions, their workflows. Different mental models. Different expectations. Real feedback.

The software stops being personal project. Starts being product.

That’s what Tuesday’s milestone means. Not just “two people invited.” But “development paradigm shifted.”

Lessons from alpha preparation

Lesson 1: Documentation reveals gaps

Writing user-facing instructions exposes missing features. Cursor found password blocker by documenting setup flow.

Lesson 2: Agent initiative compounds

Morning: Agent learns to start Docker without asking. Afternoon: Agent discovers critical issue and fixes it proactively.

Each initiative moment builds confidence for next one.

Lesson 3: Timing matters

Password fix deployed at 5:20 PM. Invitations sent at 5:20 PM. Not coincidence. Deliberate sequencing: Fix before announce.

Lesson 4: Tidying enables growth

87 files archived. 71 files organized. Dead code removed. Foundation cleaned before expansion.

Lesson 5: First impressions are critical

Without password fix, every alpha tester hits blocker immediately. First experience: frustration. Hard to recover from.

With password fix, onboarding works. First experience: smooth setup. Builds confidence.