Prepare portfolio README review

A typed scaffold plus a fleshed-out example. Replace every field with your real project; the section order is the load-bearing part.

type PortfolioReadme = {
  oneLineSummary: string;       // 12-18 words. The product, the user, the outcome.
  problem: string;              // One paragraph. What hurt before this existed.
  myRole: string;               // Auditable verbs. What you owned, what you didn't.
  technicalChoices: string[];   // 3-5 bullets. Each names a decision and the alternative.
  whatToLookAt: string[];       // 3-5 file paths or PR links a reviewer can open in 60 seconds.
  whatItIsNot: string;          // The OUT-of-scope line that prevents wasted nitpicks.
  liveLink?: string;            // Working demo or screencast.
  metricsOrEvidence: string;    // Numbers, latency, adoption, before/after, or a real user quote.
  whatIWouldDoNext: string;     // Honest next step. Builds credibility, not a bug list.
};

const example: PortfolioReadme = {
  oneLineSummary:
    'A keyboard-first command palette for trader workflows. Cuts mean-time-to-action from 4.1s to 0.9s.',
  problem:
    'Traders run identical 6-step workflows dozens of times per session. The existing UI required mouse navigation through three nested menus. Mistakes during the rapid Friday open caused at least one duplicate order per session per user.',
  myRole:
    'I designed and built this in 9 days as a personal project. I wrote the ranker, the keybinding layer, and the React component. I shipped a CI script that lints command names against a duplicate registry. I did not have backend, real trader data, or auth — every fixture is synthetic.',
  technicalChoices: [
    'Pure ranker (prefix > word-boundary > subsequence) chosen over Fuse.js to keep bundle small and behavior auditable. Fuse.js would have been faster to author but harder to defend in a code review.',
    'Reducer-driven open/close/active-index state. Tested without rendering. Avoided useState soup.',
    'Vanilla CSS-in-JS via styled-components rejected; Tailwind kept the project small and matched the production stack at a target employer.',
    'Strict ARIA pattern (role=dialog + role=listbox + aria-activedescendant). Verified with manual VoiceOver pass; clip in the README.',
  ],
  whatToLookAt: [
    'src/palette/rank.ts (40 lines) — the ranker, fully unit-tested.',
    'src/palette/Palette.tsx (120 lines) — the React component with focus management.',
    'src/palette/keybinds.ts (30 lines) — global Cmd/Ctrl+K binding.',
    'tests/palette/rank.test.ts (60 lines) — every ranking branch is covered.',
  ],
  whatItIsNot:
    'This is not a Slack-grade fuzzy search. It does not handle phonetics, multi-word reordering, or user-personalized ranking. The intent is to demonstrate that I can ship a tight UI primitive with measurable improvement, not a full Algolia replacement.',
  liveLink: 'https://example.com/palette-demo (synthetic data; no auth needed)',
  metricsOrEvidence:
    'Side-by-side video shows mean time-to-action dropping from 4.1s to 0.9s on a fixed 12-action benchmark. A small user test (n=4 friends in trading) reported zero misclicks after two minutes of practice.',
  whatIWouldDoNext:
    'Add a per-user MRU bias to the ranker (last-used commands surface higher) and a Storybook page so reviewers can drive every state without running the demo app.',
};

Convert the answer into observable behavior. In a mid-senior interview, say which behaviors are covered by unit tests, interaction tests, accessibility checks, and one browser smoke path.

// "Test" for the README = a 90-second hiring-manager skim.
// Open the README cold and ask:
// 1. Can I tell what this is in 10 seconds? (one-line summary)
// 2. Can I tell why it matters? (problem paragraph)
// 3. Can I find ~5 files I would read in a real review? (whatToLookAt)
// 4. Can I see evidence it works? (live link, video, or metric)
// 5. Can I see what is deliberately OUT? (whatItIsNot)
// If any answer is no, the README is failing the cold-skim test.

Shows whether your communication matches the level of ownership expected from senior frontend engineers.

• Use a real project or credible constructed scenario.
• Name your ownership directly.
• Include a tradeoff, outcome, and what you would do next.

• Open with context and user or business risk.
• Describe the technical decision and your ownership.
• Close with measurable outcome, learning, and relevance to the target role.

• A polished story is useful, but over-rehearsed answers can sound detached from real engineering judgment.
• Depth matters more than listing many technologies.

• Interviewer asks for your personal contribution.
• Metric is unavailable or ambiguous.
• The story exposes a skill gap you need to frame honestly.

• Say the answer aloud in two minutes.
• Write one follow-up technical detail.
• Prepare one honest limitation and ramp-up plan.

• What would a staff engineer have done differently?
• What evidence would a hiring manager trust?