CortexBuild — User Stories (v0.1)¶

Two personas (toggleable per user). Two surfaces (A: Legacy Modernisation, B: Backlog Burn-Down).

Personas¶

Persona 1 — Priya, PM at a SaaS company (50-person eng org)¶

Owns product roadmap; doesn't code
Frustrated that small fixes take weeks to ship because senior engs are on big modernisation work
Reads PRs only when blocking; trusts engineering to enforce quality
Pain: "I file a bug Monday, it's fixed in 3 weeks"

Persona 2 — Devansh, staff engineer multiplexing 4 projects¶

Manages 4 services across 2 teams
Wants to delegate "boring" work (deps upgrades, test backfilling, documentation) to free up time for architecture
Reads every PR
Pain: "I never get to the technical-debt backlog"

Surface A — Legacy Modernisation¶

Story A1: First-time project onboarding¶

As Devansh When I connect a 150k-LOC Django repo to CortexBuild I want CortexBuild to analyse the codebase and propose a modernisation roadmap So that I get a starting point I can edit rather than a blank page

Acceptance: - Connection completes in < 5 min (clone + toolchain install) - 4-pass analysis completes in < 30 min - Output includes: tech debt heatmap, inferred conventions, proposed roadmap (15–30 issues) - I can edit/reorder/discard issues before approving - Approved roadmap shows up as GitHub Issues in my repo

Story A2: Confirming inferred conventions¶

As Devansh When CortexBuild detects "all API handlers use @with_error_handling" and asks if it should enforce I want to see 3–5 example files where this is true So that I can confirm before turning it into an enforced rule

Acceptance: - UI shows file:line citations - I can click any citation → opens in GitHub - Options: "Enforce", "Advisory only", "Discard" - My decision is remembered and explained in .CortexBuild/rules/inferred/

Story A3: Approving the modernisation roadmap¶

As Priya When CortexBuild shows me a 23-issue roadmap for our Django modernisation I want plain-English summaries (not technical jargon) So that I can prioritise based on business impact

Acceptance: - Each issue has: business-impact summary, estimated effort, risk level, blocker chain - I can drag-reorder - I can tag issues "this quarter / next quarter / later" - CortexBuild suggests sequencing based on dependencies - Approval emits issues to GitHub with these labels

Story A4: Watching the team work¶

As Priya When I open the CortexBuild dashboard I want to see what the agents are working on right now, in business language So that I can answer "what's shipping this week" without asking engineering

Acceptance: - Timeline shows: "Builder agent is implementing 'Add CSRF tokens to legacy forms'" - Estimated remaining time visible - Click any task → see plain-English plan + Critic review - "Tech-lead view" toggle reveals diff, test output, security findings

Story A5: Reviewing a CortexBuild-opened PR¶

As Devansh When CortexBuild opens a PR titled "Migrate users module to async views" I want the PR body to include: plan, self-audit, evidence, rollback notes, confidence score So that I can review in 5 minutes instead of 30

Acceptance: - PR body has a structured template (plan, pre-mortem, evidence, rollback) - Confidence score < 0.7 → PR opens as DRAFT - Self-audit YAML pre-fills checks I'd otherwise do manually - Citations link to file:line for every claim

Story A6: PR rejected → ledger learns¶

As Devansh When I close a CortexBuild PR with "this breaks our naming convention" I want CortexBuild to record the failure, propose a new rule, and never make the same mistake again So that the agent gets smarter with my codebase

Acceptance: - Closing comment triggers a post-mortem flow - CortexBuild drafts a .CortexBuild/rules/inferred/rule-naming-X.md - I review and either accept (becomes enforced) or reject (logged as discarded) - Future PRs that would violate the rule are blocked at Critic gate

Story A7: Budget exhausted mid-modernisation¶

As Priya When the project's monthly LLM budget is used up I want CortexBuild to pause, show me what was spent on what, and ask if I want to top up So that I'm never surprised by a bill

Acceptance: - Budget alert at 80% (email + UI banner) - Hard pause at 100% - Cost dashboard: per-agent, per-task, per-provider - Top-up = update billing limit; agents resume automatically

Surface B — Backlog Burn-Down¶

Story B1: Connecting Linear¶

As Priya When I connect our Linear workspace and select the "Bugs" project I want CortexBuild to triage every ticket: complexity, confidence, suggested next action So that I see which tickets it can handle autonomously

Acceptance: - Linear OAuth flow completes in 60s - Triage runs across 50 tickets in < 5 min - Each ticket gets: complexity (S/M/L/XL), confidence (0–1), suggested action - I can override classifications

Story B2: Auto-batch of S tickets¶

As Priya When I select 10 S-complexity tickets with confidence > 0.85 I want CortexBuild to work through them in parallel, opening PRs as it finishes So that my backlog visibly shrinks

Acceptance: - "Start batch" button kicks off all 10 - Real-time progress per ticket - PRs open as they're ready - Failed tickets surface with error explanation - I can pause/cancel the batch anytime

Story B3: M ticket — plan-then-execute¶

As Devansh When CortexBuild picks up an M ticket ("Add filter UI to orders page") I want to see the plan first and approve before code is written So that I don't waste cycles on the wrong direction

Acceptance: - Plan includes: API changes, DB changes, frontend changes, test plan, pre-mortem - I can edit the plan in-line - Critic review attached - Approve → execution proceeds; Reject → re-plan with my feedback

Story B4: XL ticket — breakdown suggestion¶

As Devansh When CortexBuild encounters an XL ticket it can't handle I want it to propose breaking it into smaller tickets So that I'm not blocked by my own ticket sizing

Acceptance: - Confidence < 0.4 → triggers breakdown suggestion - CortexBuild drafts 3–7 sub-tickets with dependency arrows - I approve breakdown → sub-tickets created in Linear - Original ticket marked "broken down"

As Devansh When I have 3 projects on CortexBuild I want rule packs and inferred conventions to be reusable across projects (with my opt-in) So that I don't onboard from scratch every time

Acceptance: - "Copy rules from Project X" available at onboarding - Diff view: which rules conflict with newly-inferred ones - My team-level skill library persists

Cross-cutting stories¶

Story X1: Adjusting autonomy mid-project¶

As Devansh When I trust CortexBuild more after 2 weeks of clean PRs I want to relax "merge to main" from Approve → Notify So that I unblock the team further

Acceptance: - Autonomy matrix editable any time - Changes audit-logged - "Below recommended" choices show warning - Can revert anytime

Story X2: Multi-user collaboration¶

As Priya When I'm OOO and Devansh needs to approve a PR merge I want him to be able to take over my approval queue So that work isn't blocked

Acceptance: - Multi-user per project - Approval queue is project-level, not user-level - Anyone with admin role can decide - Decision attributed to actor in audit log

Story X3: Disaster — CortexBuild opened a bad PR that got merged¶

As Devansh When I discover a CortexBuild PR caused a prod issue I want to easily roll back AND make sure it never happens again So that trust is restored

Acceptance: - "Revert this PR" button in CortexBuild UI - One-click post-mortem creation - Post-mortem becomes ledger entry - Critic gate updated to block the failure class - Email digest to user: "added recurrence guard"

Story X4: Cost visibility¶

As Priya When I open the cost dashboard I want to see: $ this month, per-task breakdown, comparison vs last month, projection So that I can defend the spend to my CFO

Acceptance: - Real-time cost meter - Filter by agent, provider, task, week/month - CSV export - Configurable monthly budget + alerts

Story X5: Audit export for compliance¶

As Devansh (in a regulated company) When our compliance officer asks "who approved this production deploy?" I want to export an audit log for any time range So that we can satisfy SOC2 controls

Acceptance: - Export format: JSON + CSV - Includes: actor (user OR agent), action, target, payload, timestamp - Tamper-evident (hash chain across entries) - 7-year retention for enterprise tier

Anti-stories (what we explicitly will NOT support in v1)¶

"Build my new app from scratch" — greenfield. Out of scope.
"Make decisions about my company's tech stack" — too high-context. We encode best practices; we don't override your CTO.
"Replace my developers" — we augment, not replace. Approval gates make this explicit.
"Operate without git" — git is the API. No git = no CortexBuild.
"Work on private GitLab/Bitbucket without webhook access" — we need webhooks for ticket triggers.
"Modify production data directly" — never. Always proposes a migration PR.
"Work offline with no LLM" — we orchestrate LLMs; without one, we have nothing.