Onboarding

Welcome. This guide is everything you need to start filing high-quality bug reports on your first day. Read it once end-to-end before you touch the app — the patterns will save you hours later.

Your first assignment is to test Hackorda itself. We use our own QA tool on our own product. The cycle is called "Hackorda Onboarding — QA shake-down". Your goal during week one: complete every test case in hackorda-test-cases.md and file at least one issue per real defect you find.

1. The job in one paragraph

You are the last line of defence between a broken feature and a paying user. Engineers ship. PMs prioritize. Designers make it pretty. You break it on purpose, write down exactly how, and hand the engineer a report so clear they fix it without asking a single follow-up question. A great QA writes bugs the way a journalist writes news: who, what, when, where, why, and a screenshot.

You don't need to know how to code. You need to be observant, persistent, and allergic to "works on my machine."

2. Glossary — the words we use

3. Day 1 setup checklist

Tick each item before opening any test cases.

• You have a Hackorda account and can sign in at /sign-in
• An admin has assigned you to the "Hackorda Onboarding — QA shake-down" cycle
• You see the cycle in the QA section sidebar at /app/test-cycles
• The cycle status shows active (not planned/review)
• You can open the brief and read the scope
• You have a way to record your screen (built-in: macOS ⌘⇧5, Windows Win+G, browser: Loom or similar)
• You have at least two devices/browsers ready: desktop Chrome + mobile (real phone or Chrome devtools mobile mode)

Stuck? Ping your lead. Don't start testing without an active cycle assignment — you won't be able to file issues.

4. The core loop — every testing session

   ┌────────────────────────────────────┐
   │  Open cycle  →  Start run          │
   │                    ↓                │
   │              Use the product        │
   │              like a real user       │
   │                    ↓                │
   │             Find something off?     │
   │                ┌───┴───┐            │
   │              yes       no           │
   │                ↓        ↓            │
   │            File issue  Continue     │
   │                ↓        │            │
   │              ←─────────┘            │
   │                    ↓                │
   │                End run              │
   │             (write notes)           │
   └────────────────────────────────────┘

Always start a run before testing. The run captures your browser and OS so engineers know whether your bug is platform-specific. Always end your run when you stop — half-open runs clutter the cycle dashboard.

5. Filing an issue — the gold standard

Every bug you file ships through this form. Read this section twice.

5.1 Title — one line, scannable

A great title fits this template:

[Where] — [What's wrong] when [trigger]

A reader should know whether to care from the title alone. Aim for 60-90 chars.

5.2 Severity — pick honestly

Calibration rule: if the bug stops a user finishing their goal, it's high or critical. If they finish their goal but mutter at the screen, it's medium or low.

5.3 Bug type — what kind of broken

Pick the closest match. If you're not sure, leave it blank — it's optional.

5.4 Attachments — required, and worth the time

You need at least one screenshot or recording to submit. Two rules:

1. Show the bug, not the desktop. Crop or annotate so the reader's eye lands on the broken element. Excalidraw, Skitch, or just an arrow in Preview works.
2. Recordings beat screenshots for any interaction bug. A 10-second ⌘⇧5 clip showing the broken click is worth a thousand stack traces.

For each issue attach:

• Screenshot of the broken state (what it looks like)
• Screen recording of the steps that triggered it (only if interaction-based)
• Console screenshot if there's a JS error (right-click → Inspect → Console tab)

5.5 Repro steps — the part engineers will actually read first

Format every set of steps as a numbered list:

1. Open https://hackorda.kz/sign-in in Chrome 142 on macOS 14.4
2. Sign in as qa-tester@hackorda.kz
3. Click "Quiz" in the left sidebar
4. Click "Start" on any quiz
5. Type "abc" into the answer field and press Enter

Rules:

• Start at step 1 with the URL or screen, not "go to the page".
• One action per step. If you want to combine, you're hiding a step.
• Mention the data you used. ("Type 'abc'" not "Type something".)
• Mention the browser/OS for any non-functional bug.

5.6 Expected vs Actual

Both are required for a great report.

Expected: After clicking Submit, the answer is graded and the next question loads.
Actual:   Submit button greys out for 2 seconds, then nothing happens. Console shows
          "TypeError: Cannot read property 'id' of undefined" in QuizPage.tsx:142.

Engineers debug the gap between expected and actual. Spell it out.

6. The four mistakes new testers make

1. One issue, multiple bugs. "Profile page is broken" → split into 4 issues: one per actual defect.
2. Repro steps that assume context. "Click the button" — which button? Always reference the visible label or screenshot.
3. Severity inflation. Calling everything critical trains the team to ignore your reports. Reserve critical for shipping blockers.
4. No attachment. "I saw it" is not a bug report. If you can't capture it, keep trying until you can.

7. Drafts and the "I'll finish this later" workflow

Every issue form has a Save draft button. Use it:

• You found something but need more info before filing
• You're mid-investigation and need to grab lunch
• You're filing five issues in a row and want to batch-submit

Drafts live under All Issues → Mine → status: draft. They never count toward the cycle's open-issue total until you hit File issue.

You can edit a draft, attach more media, then submit. Once submitted (status becomes open), you can still edit until a lead triages it.

8. Triage states — what happens after you submit

You'll spend a chunk of week 2 verifying fixed issues. That's normal.

Approving a bug end-to-end — from triage through verification through paid — is documented in approval-process.md.

9. Daily / weekly rhythm

Every test session:

• Start a run before clicking anything
• File issues as you find them — don't batch (you'll forget details)
• End the run with a one-line summary in notes

Every day:

• Check All Issues → Mine → status: fixed for issues that need verification
• Skim your draft list — finalize or delete

Every week:

• Read the cycle dashboard — what's the issue count, who's reporting most, are there gaps in coverage?
• Bring three observations to the team sync (not bug reports — observations: "the form felt slow", "the empty state copy was confusing")

10. Where to look when stuck

• Section sidebar at /app/test-cycles — your home base
• All Issues view at /app/issues — every issue you can see, filterable
• Cycle brief — open the brief side panel on the cycle detail page; it contains scope, test accounts, links to Notion/Linear
• The lead — Slack first, escalate if no response in an hour

11. What "great" looks like

You're doing this right when:

• ✅ Your bug reports get triaged without anyone asking you a follow-up question
• ✅ Engineers thank you for the recording (yes, this happens)
• ✅ You catch one major issue per cycle that the team didn't expect
• ✅ Your severity calibration matches the lead's after triage 80%+ of the time

You're doing this wrong when:

• ❌ Half your issues come back as cant_reproduce
• ❌ Engineers ask "what browser?" in the comments
• ❌ Your title is "doesn't work"

12. Your account, your tier, and the test-data rule

Read this before you run test groups L–O — those cover the close-out, cycle-aging, and role/payout features. For how those features behave, see feature-guide.md.

Your account is a plain admin

The owner creates your account and assigns its role. You get a plain admin account — not a super_admin. The two tiers are split so that everyday QA work and money-/access-sensitive actions need different levels of trust.

As a plain admin you CAN:

• Triage issues — reject and request info
• Manage cycles and run fix-verification
• Use the batch Linear export on the admin cycle page
• Use every cycle-aging and list-view feature (aging pill, progress bar, sorts, table column, Board view)

As a plain admin you CANNOT — these are super_admin-only:

• Approve a payout (the triage "approve" decision)
• Disburse payouts (batch-pay / run-batch)
• Change a user's role
• See the Audit Log at /app/admin/audit

If a test case needs a payout approved or paid, or needs the Audit Log opened, the owner (a super-admin) has to set it up or run it. Those cases say so in their Preconditions — don't skip them, coordinate with the owner.

There's also a self-dealing guard: nobody — not even a super-admin — can approve or pay out a payout for an issue they themselves reported. That's intended behaviour, not a bug.

The test-data rule — read this twice

You test only inside clearly-labelled TEST organizations, products, and cycles. Never touch live client data. You hold an admin account, which means real triage and cycle controls are in your hands — a mis-click on a real client's cycle is a real incident. If you can't tell whether something is test data, stop and ask the owner before acting.

Next: skim feature-guide.md, then open hackorda-test-cases.md and start with TC-01.