Junior Developer / GitHub Portfolio Beginner

30 ChatGPT prompts for junior developers to build GitHub README stories

Your GitHub is your portfolio. In 2026, it is also the first interview you give. Recruiters do not boot your app. They open your repo, read the top of the README, and decide in 90 seconds if you get a callback. This guide gives you 30 ready-to-paste ChatGPT prompts for junior developer GitHub README story writing, plus the 4-part anatomy, the 2026 stats, and the 14-day sprint to get five repos that actually move the needle.

The 2026 number that should scare you (in a good way): GitHub crossed 180 million developers as of late October 2025, and 1.4 million first-time open-source contributors joined in 2024 alone, with first-time contributors now behind a third of the activity in many GenAI projects (GitHub Press, Oct 30 2025; Octoverse 2024). If your README reads like an instruction manual, you are blending into a crowd that grew almost overnight.

Quick answer (read this first)

If you only have 60 seconds, do this:

Open the repo of your most-shipped side project.
Run Prompt 1 (Project Pitch) to write your hero paragraph.
Run Prompt 2 (Problem → Solution → Outcome) to fill the “Why” section.
Run Prompt 9 (Demo & Screenshots) to script a 15-second GIF story.
Run Prompt 27 (Profile README banner) so your github.com username page matches.

That is the minimum viable README story. Everything else in this guide tightens the screws.

“A README is not documentation. It is the cover of your book’s first chapter. If the cover is generic, nobody reads chapter two.” - paraphrased from a recurring theme across Open Source Guides’ Starting a Project guide.

Why your README looks like an instruction manual (with a 2026 stat)

You wrote the README to remind yourself what the project does. That is the first mistake. A README is a pitch, not a memory aid. The Open Source Guides put it bluntly: a good README answers “what does this project do, why is it useful, how do I get started, and where do I get more help” (Open Source Guides). Most junior READMs answer only “how do I install this,” and stop there.

The cost is concrete. The Stack Overflow 2024 Developer Survey found that roughly 62% of professional developers say a strong open-source portfolio matters “somewhat” or more when evaluating a candidate, and the share jumps higher for junior roles where the resume is thin. While that exact number shifts year to year, the directional finding has been consistent since 2022. Combine that with the fact that GitHub’s Octoverse 2024 report logged 5.2 billion contributions to public and open-source repos in 2024, and you see the issue: there are a lot of repos competing for a recruiter’s thumb-stop.

A second reason your README looks like a manual: you ship features, not stories. Conventional Commits push you to write feat: and fix: lines, which is great for changelogs and terrible for prose (Conventional Commits v1.0.0). Your commit log is a feature inventory. Your README is the why behind those features. The 30 prompts below turn that inventory back into a story.

The third reason is plain polish. Recruiters in 2026 skim READMs the same way they skim TikTok: hero line, screenshot, one bullet on impact, and a “what’s next” link. If your README buries the lede under three H2s called “Installation / Usage / License,” you are training them to bounce. We will fix that.

The 4-part README story anatomy

Every strong README I have ever written for a junior dev portfolio follows the same four-part anatomy. Memorize it. Then the prompts become a paint-by-numbers exercise.

The Hook (top 3 lines above the fold). One sentence on what it is, one sentence on who it is for, one sentence on why it matters now. The Open Source Guides call this “name, description, badges” (Make a README), but for a story README, we want hero line, social proof, and a hero GIF.
The Why (problem → solution → outcome). What pain existed, what you built, what changed because of it. Numbers belong here. So do trade-offs.
The Demo (screenshots, GIFs, terminal captures). Shields.io badges, Mermaid.js diagrams, terminal recordings from asciinema, and 3–5 screenshots.
The Trail (architecture, stack, contributing, what’s next). This is where the technical reader falls in love. Use Read the Docs, MkDocs, or Docusaurus for the deep docs. Keep the README scannable.

That is the anatomy. The rest of the article is 30 prompts that fill each part.

SECTION 1: Project-pitch prompts (prompts 1–5)

These five prompts handle the hook and the “why” - the parts a recruiter sees in the first scroll.

Prompt 1 - The 3-line hero paragraph

Purpose/context: Replace the generic “A tool for X” first line with a hero paragraph a non-technical recruiter can grasp in 8 seconds. The first line of a README is the most-rewritten line in software. Most junior dev READMs open with the project’s name and a noun. That is not a hook. A hook is value to a specific reader.

The prompt:

You are a senior product marketer writing the top 3 lines of a GitHub README.

Project name: [YOUR PROJECT NAME]
What it does (one sentence): [e.g., a CLI that converts CSV files into SQL insert statements]
Who it's for: [e.g., junior data analysts who don't know SQL]
Tech stack: [e.g., Python 3.12, Click, Pytest]
Why it matters now: [e.g., most teams still do this in Excel]

Write exactly 3 lines:
Line 1: A hero statement that names the audience and the outcome.
Line 2: One concrete example of input → output.
Line 3: A social-proof line (e.g., "Used by 200+ analysts" or "Replaces a 40-minute manual task").

Constraints:
- Plain English, no jargon.
- No emoji, no badges in this paragraph.
- Each line must be under 90 characters.
- Avoid the words "simple", "easy", "powerful", "lightweight".

Example output:

csv2sql turns 40-minute CSV cleanup into a 1-line command for junior data analysts.
Drop a 10,000-row export.csv, get a ready-to-paste INSERT file back.
Used by 200+ analysts at Series-A startups to skip the Excel handoff.

Pro tips:

Write three versions, not one. Ask ChatGPT for a “more direct” and a “more human” variant. Pick the one that sounds like a tweet you would actually send.
Lead with the audience, not the project. “For junior data analysts who…” beats “A tool for converting CSVs.” Always.
If you have zero users, drop the social proof line. Replace it with the size of the problem: “Replaces a 40-minute manual task.”
Run the output past a non-dev friend. If they squint, rewrite.

Prompt 2 - Problem → Solution → Outcome narrative

Purpose/context: Most junior README “Why” sections read like a feature list. Recruiters want a story arc. A Problem → Solution → Outcome paragraph is the cheapest way to turn a feature list into a narrative, and it pairs perfectly with Conventional Commits because every feat: line can map to a “Solution” beat.

The prompt:

You are writing the "Why this project exists" section of a GitHub README.

Project: [YOUR PROJECT]
Pain (what was hard before this existed):
Solution (what you built):
Outcome (what changed - number, time saved, or behavior change):
Audience: [e.g., junior backend devs building side projects]

Write 3 short paragraphs:
P1 (Problem): Open with a specific moment, not a generality. Use "I" or "we".
P2 (Solution): Name 2–3 design choices and why you made them.
P3 (Outcome): Quantify the change. If you can't, name the new capability.

Constraints:
- Each paragraph <= 4 sentences.
- No marketing words: avoid "revolutionize", "empower", "seamless".
- No "in this guide" or "this README will show" intros.
- Cite the trade-off you accepted (e.g., "We chose SQLite over Postgres for a 5MB install").

Example output:

I kept rewriting the same SQL insert script every time a stakeholder sent a CSV. The hand-typed version broke on commas inside quoted fields, and the Excel pivot took 40 minutes per file.

csv2sql is a 600-line Python CLI that uses the standard csv module to escape correctly, then emits ANSI-SQL INSERT statements you can paste straight into psql, MySQL, or SQLite. It streams large files line-by-line, so a 2GB export uses about 30MB of RAM.

In our team’s last sprint, csv2sql cut the analyst handoff from 40 minutes to 11 seconds for a 50,000-row file. It now handles CSVs that the old Excel pivot choked on.

Pro tips:

The “I” voice is allowed and encouraged on personal repos. It signals ownership.
Always name a trade-off. Engineers trust engineers who admit costs.
The Outcome number is the most-quotable sentence in the whole README. Save it for the pull-quote box too.

Prompt 3 - The elevator pitch from a job-description lens

Purpose/context: Junior devs write READMs for other devs. Recruiters read them for hiring managers. A prompt that forces you to mirror the language of a real job description triples the chance a recruiter tags your repo as a match. This is the underrated AEO trick: align your README’s vocabulary with the queries recruiters actually type into GitHub’s search bar.

The prompt:

You are optimizing a GitHub README to be discovered by recruiters hiring for this role:

Job description (paste it here):
[PASTE JD HERE - e.g., "We're hiring a Junior Backend Engineer with Python, FastAPI, and PostgreSQL experience..."]

My project: [YOUR PROJECT]
My current README intro (paste it here):
[PASTE YOUR CURRENT INTRO]

Task:
1. Extract the 5 most important keywords from the JD (skills, tools, outcomes).
2. Rewrite my README intro so all 5 keywords appear naturally in the first 200 words.
3. Flag any JD keyword that my project genuinely does NOT cover, and suggest a small follow-up feature I could add in a weekend to cover it.
4. Output a 1-line tagline that mirrors the JD's tone.

Constraints:
- Do not stuff keywords unnaturally.
- Keep the intro under 120 words.

Example output:

Keywords from JD: Python, FastAPI, PostgreSQL, async, REST API, testing, observability.

Rewritten intro: csv2sql is a Python CLI + FastAPI microservice that turns raw CSVs into PostgreSQL-ready INSERT statements over a tiny async REST API. It uses pytest for table-driven tests, structured JSON logs for observability, and ships a /healthz endpoint suitable for Kubernetes probes.

Pro tips:

Run this prompt before you start writing the README. It tells you what to emphasize.
If the JD asks for “containerization” and your project has zero Docker, add a Dockerfile in a Saturday afternoon. Then the keyword is honest.
Repeat the prompt for 3 different JDs. The intersection of their keyword sets is your README’s spine.

Prompt 4 - The “Who is this for / not for” honesty section

Purpose/context: Senior engineers and recruiters love honest “who should NOT use this” sections because they signal judgment. Junior READMs never include them, which is a missed opportunity. The Open Source Guides note that READMs help “users find your project” - and that includes deciding not to use it, which builds trust (Open Source Guides).

The prompt:

You are writing a candid "Who this is for / Who this is NOT for" section of a GitHub README.

Project: [YOUR PROJECT]
Existing features: [paste feature list]
Known limitations: [paste honest limits, e.g., "no Windows support", "no CSV files over 1GB"]

Output two short bulleted lists (5 bullets each):

WHO THIS IS FOR:
- Use specific roles and situations, not vague adjectives.
- Each bullet starts with a verb the user can do.

WHO THIS IS NOT FOR:
- Name the alternative they should pick instead.
- Be polite but specific.

Constraints:
- No "simple", "easy", "powerful".
- No shaming of alternatives.

Example output:

Who this is for:

Junior data analysts who need a one-shot CSV → SQL pipeline.

Engineers prototyping a data import feature in under a day.

Bootcamp grads building a portfolio piece to discuss in interviews.

Who this is NOT for:

Production ETL at scale - use Airflow or dbt instead.

Non-CSV sources (Parquet, JSON, XML) - use Pandas or DuckDB.

Teams who need a GUI - this is a CLI-only tool.

Pro tips:

The “NOT for” list is a credibility signal. Don’t skip it.
If you don’t know who the project is NOT for, you don’t know who it IS for. Rewrite Prompt 1.

Prompt 5 - The TL;DR box that doubles as a hero GIF caption

Purpose/context: A TL;DR pull-quote box at the very top of a README is one of the highest-impact readability wins. It also acts as a meta description for AEO when scrapers like Perplexity or Google’s AI Overviews index your repo. This prompt writes a TL;DR plus a GIF caption in one go.

The prompt:

You are writing a TL;DR callout for the top of a GitHub README. It must work as:
1. A 1-paragraph README intro (max 50 words).
2. A pull-quote box the reader sees before scrolling.
3. A GIF caption that will be embedded under the hero image.

Project: [YOUR PROJECT]
Hero metric: [e.g., "10× faster than the Excel workflow it replaces"]
Stack: [e.g., Python, Click, SQLite]

Output:
- TL;DR paragraph (50 words max, plain English, present tense).
- Pull-quote version (one sentence, max 25 words, can be a quote from "the maintainer").
- GIF caption (max 12 words, ends with a verb).

Constraints:
- No emojis.
- No marketing adjectives.
- The pull-quote must be a complete sentence with a verb.

Example output:

TL;DR. csv2sql is a Python CLI that turns any CSV into a clean INSERT SQL file in under 10 seconds - no Excel, no manual quoting, no broken edge cases.

“It’s the SQL generator I wish I had during my data-bootcamp capstone.” - the maintainer

GIF caption: “Drop a CSV. Get a SQL file. Ship.”

Pro tips:

The pull-quote is a great place to plant a future interview soundbite. Reuse it on LinkedIn.
Cap the GIF at 12 MB. GitHub renders it inline; bigger files make recruiters bounce.

SECTION 2: Demo & screenshot prompts (prompts 6–10)

Visuals decide whether the README gets shared. These prompts script the GIF, the screenshot, the Mermaid diagram, and the terminal capture.

Prompt 6 - A 15-second hero GIF script

Purpose/context: A README with a hero GIF converts 2–3× better than one without, anecdotally reported by maintainers in the ReadME Project community and observed in A/B tests run by indie devs. A 15-second GIF is the sweet spot - long enough to show a flow, short enough to autoplay without annoying a recruiter.

The prompt:

You are scripting a 15-second hero GIF for a GitHub README hero image.

Project: [YOUR PROJECT]
The one feature a new user MUST see to "get it": [e.g., turning a CSV into SQL]

Output a frame-by-frame script (1 second per frame, 15 frames total):

Frame 1-3: Setup. The user opens a terminal in an empty directory.
Frame 4-7: Action. The user runs the main command. Show a small, readable terminal capture.
Frame 8-11: Result. The output file appears, with one row highlighted to show the data shape.
Frame 12-15: Close-up. The README's "Quick start" code block is highlighted in a browser.

For each frame, output:
- What is on screen (terminal, browser, editor).
- The exact text the user sees (so I can paste it into asciinema or VHS).
- A 1-sentence note on what to highlight (e.g., "zoom on the row count").

Constraints:
- Use a 12pt monospace font.
- 80×24 terminal, no colors that fail contrast checks.

Example output:

Frame 4 - terminal: > csv2sql ./export.csv --table customers Frame 8 - terminal: ✓ Wrote 50,000 INSERT statements to ./export.sql (1.2s) Frame 12 - editor: highlight line INSERT INTO customers (id, email) VALUES (1, 'a@x.io');

Pro tips:

Use VHS (by Charmbracelet) or asciinema to record the GIF. VHS lets you write the script as code, so the GIF is reproducible.
Always include a 1-second “still” at the end so recruiters on slow connections can read the result.
2× pixel ratio. Recruiters view on retina MacBooks; blurry GIFs read as “low effort.”

Prompt 7 - Screenshot alt text and caption generator

Purpose/context: Screenshot alt text is the most-skipped accessibility win in READMEs. Search engines (and AI Overview scrapers) read alt text. Recruiters using screen readers (yes, they exist) read alt text. This prompt writes alt text that doubles as SEO.

The prompt:

You are writing alt text and a short caption for 5 screenshots in a GitHub README.

Project: [YOUR PROJECT]
Screenshots (in order):
1. [e.g., main dashboard]
2. [e.g., settings page]
3. [e.g., terminal output]
4. [e.g., Mermaid diagram]
5. [e.g., contributors graph]

For each, output:
- alt text (max 125 characters, describe the image, do not start with "image of")
- caption (max 12 words, shown under the image, ends in a period)

Constraints:
- alt text must be useful to a screen reader user.
- caption should explain WHY the screenshot matters, not what it literally is.
- No marketing adjectives.

Example output:

alt="csv2sql main dashboard showing a 50,000-row CSV preview with a Run button" caption: “The dashboard surfaces the row count and column types before you run a job.”

Pro tips:

If you can’t fit the alt text in 125 chars, you have too much in the screenshot. Crop.
Alt text is the perfect place to repeat a primary keyword (“GitHub README story,” “CSV to SQL CLI”). It is honest, not spammy.

Prompt 8 - Mermaid.js architecture diagram from a code walkthrough

Purpose/context: Mermaid.js diagrams render natively on GitHub. A good architecture diagram turns a 2,000-word README into a 1-glance story. Junior READMs skip this because writing Mermaid by hand is painful. ChatGPT can read your folder structure and emit the syntax.

The prompt:

You are writing a Mermaid.js diagram for a GitHub README.

Project: [YOUR PROJECT]
Source tree (paste here):
[PASTE TREE OUTPUT OF `tree src/`]

Architecture intent (one sentence):
[What is the data flow? e.g., "CLI reads CSV, streams to parser, writes SQL."]

Output:
1. A `flowchart LR` Mermaid block (5–9 nodes max).
2. A short paragraph (3 sentences) explaining the diagram in plain English.
3. The exact markdown wrapper to paste into the README.

Constraints:
- Use direction LR (left-to-right) - reads better on mobile.
- Node labels <= 4 words.
- Use a `subgraph` for any "internal" module.

Example output:

```mermaid
flowchart LR
  A[CSV file] --> B[Reader]
  B --> C[Type Inferer]
  C --> D[SQL Emitter]
  D --> E[Output .sql]
```

The reader streams the file in 8KB chunks. The type inferer samples the first 1,000 rows to pick INTEGER, TEXT, or TIMESTAMP. The SQL emitter writes inserts in batches of 500 to keep memory flat.

Pro tips:

Keep node count under 9. More than that and the reader gives up.
If your architecture is more than 9 modules, draw TWO diagrams: “system view” and “module view.”

Prompt 9 - A terminal capture that shows the “magic moment”

Purpose/context: Some projects are CLI-first. A great terminal capture replaces five paragraphs. asciinema and charmbracelet/vhs both render in README. The prompt extracts the most “magic” 30 seconds from a longer flow.

The prompt:

You are scripting a 30-second terminal capture for a GitHub README hero.

Project: [YOUR PROJECT]
Longest "wow" command in the project: [e.g., csv2sql ./big.csv --infer --output out.sql]
What the user sees if everything works: [paste actual output]

Output:
1. A 30-second script with exact commands and timing.
2. The expected output for each command.
3. A 2-line "what just happened" summary to put under the capture.

Constraints:
- Use a real-looking directory and filenames.
- No `rm -rf` or destructive commands.
- Total wall-clock time: 30 seconds.

Example output:

$ time csv2sql ./big.csv --infer --output out.sql
✓ Inferred 12 columns (8 TEXT, 3 INTEGER, 1 TIMESTAMP)
✓ Wrote 1,200,000 INSERT statements to out.sql (38.4s)
real    0m38.412s

Pro tips:

Run the actual command and paste real output. Fake terminal output is a credibility killer.
Trim trailing blank lines and ANSI noise. Use script or VHS for clean capture.

Prompt 10 - A “before / after” comparison screenshot prompt

Purpose/context: A before/after pair sells the value of the project faster than any feature list. The catch: you have to pick the right “before.” A junior dev’s “before” is usually “nothing,” which doesn’t sell. The right “before” is “the manual way a senior engineer would do this.”

The prompt:

You are planning a "before / after" screenshot pair for a GitHub README.

Project: [YOUR PROJECT]
The "after" is: [describe the perfect output]
The "before" (manual alternative) is: [describe the painful manual workflow]
Tools the manual workflow uses: [e.g., Excel + hand-typed SQL]

Output:
1. A 1-sentence caption for the before screenshot.
2. A 1-sentence caption for the after screenshot.
3. A 2-sentence bridge paragraph explaining the time/cost difference.
4. Exact alt text for both images.

Constraints:
- The "before" must be a real workflow, not a strawman.
- Time/cost difference must be specific (e.g., "40 min → 11 sec").

Example output:

Before: screenshots/before.png - “Excel pivot + hand-typed SQL: 40 minutes for 50,000 rows.” After: screenshots/after.png - “csv2sql one-liner: 11 seconds for 50,000 rows.”

The pivot table choked on quoted commas and silently truncated 3,200 rows. csv2sql streams the file and never loads it into memory, so the same job runs in seconds and emits ANSI-SQL we can paste straight into psql.

Pro tips:

The “before” screenshot is the most underused asset. Draw it in Excalidraw or Figma if you don’t have one.
Always put the after on the right. Western readers scan left-to-right; the “after” should be the payoff.

SECTION 3: Story & context prompts (prompts 11–15)

These prompts fill the “Why this project exists” section with story, motivation, and the trade-offs that make you sound senior.

Prompt 11 - The “lessons learned” paragraph

Purpose/context: Recruiters want to see that you can learn from a project, not just ship features. The “lessons learned” section is a 6-sentence paragraph that turns your side project into a growth narrative. This is the single most-skipped section in junior READMs, and the single most-asked-about section in junior interviews.

The prompt:

You are writing a "What I learned building this" paragraph for a GitHub README.

Project: [YOUR PROJECT]
Top 3 mistakes I made while building it:
1. [paste]
2. [paste]
3. [paste]

Top 3 design decisions I'm proud of:
1. [paste]
2. [paste]
3. [paste]

The single most surprising thing I learned: [paste]

Output:
- A 6-sentence paragraph that follows this arc:
  Sentence 1: What I set out to build.
  Sentence 2: The first architectural mistake.
  Sentence 3: How I caught it (test, prod, code review?).
  Sentence 4: The fix and the trade-off it forced.
  Sentence 5: The decision I am most proud of, and why.
  Sentence 6: What I would build next, and what changed in how I think.

Constraints:
- Use "I", not "we" (this is a personal project).
- No buzzwords. Name the trade-off, not the lesson.
- Mention one specific tool or library you used in the fix.

Example output:

I set out to build a 200-line CSV-to-SQL converter. My first mistake was using pandas.read_csv for files over 1GB, which crashed the script on a 4GB export from a real customer. I caught it when a user opened an issue with a stack trace. I rewrote the reader with the stdlib csv module and a generator, which kept memory under 30MB. I am most proud of the type-inference heuristic, which samples 1,000 rows before deciding INTEGER vs TEXT. Next I would add Parquet support, and I now default to streaming readers on any project I start.

Pro tips:

Mention an issue number or a commit SHA. Concrete evidence beats abstract claims.
Junior interviewers ask “what would you do differently?” The “lessons learned” section pre-answers it. Rehearse the paragraph out loud.

Purpose/context: Engineers who can name what they would not recommend look senior. Junior READMs never include this because it feels risky. It is the single highest-credibility move you can make.

The prompt:

You are writing a "What I would NOT recommend using this for" paragraph.

Project: [YOUR PROJECT]
Honest limitations:
- [paste]
- [paste]
- [paste]

Decisions I would reverse if I started over:
- [paste]
- [paste]

Output a 4-sentence paragraph:
Sentence 1: The use case I would NOT point people to this for, and what they should use instead.
Sentence 2: The design decision I would reverse, named explicitly.
Sentence 3: The lesson that decision taught me.
Sentence 4: A one-line invitation to file an issue if a user disagrees.

Constraints:
- No hedging ("maybe", "kind of"). Be direct.
- No "this might not work for everyone" filler.
- Name a specific alternative project.

Example output:

I would not recommend csv2sql for production ETL - Airflow or dbt does that job better and with audit logs. I would reverse the decision to support both a CLI and a FastAPI server in the same package; the coupling has cost me 3 days of refactors. The lesson is to ship the CLI first, wait for two production users, then extract a service. If you disagree, open an issue - I’d rather learn from your use case than be right.

Pro tips:

This is also the prompt to use for “known issues” sections. Link to your issue tracker.
The single-line issue invitation is the cheapest way to look like a healthy open-source maintainer.

Prompt 13 - The “this is for the next junior dev” letter

Purpose/context: Open-source projects that include a “letter to the next contributor” pull in 2–4× more first-time contributions. Octoverse 2024 reported that 34% of contributors to the top “For Good First Issue” projects made their first contribution after signing up for GitHub Copilot (Octoverse 2024) - meaning first-timers are arriving faster than ever, and a warm welcome is a force multiplier.

The prompt:

You are writing a "Letter to the next contributor" section for a GitHub README.

Project: [YOUR PROJECT]
Stack: [paste]
Easiest first issue (paste a GitHub issue URL): [URL]
Maintainer name + timezone: [name, TZ]

Output a 4-paragraph letter:

P1: Welcome. Use the contributor's first name ("Hey, future maintainer -").
P2: The shortest path to your first merged PR, in 3 numbered steps.
P3: The 1 file in the repo a new contributor should read first, and why.
P4: A one-line commitment from you ("I review PRs every Tuesday").

Constraints:
- Friendly, not corporate.
- 3 numbered steps, not 5.
- Name the maintainer's first name in the commitment.
- No emoji, no exclamation marks.

Example output:

Hey, future maintainer - thanks for stopping by.

The fastest way to your first merged PR:

Read src/parser.py (it’s 80 lines, and the docstring is the spec).

Pick an issue labeled good first issue.

Open a draft PR - I’ll review within 48 hours.

Start with src/parser.py because it shows the streaming pattern the rest of the project follows. If you can write a test for the parser, you can write a test for any file in this repo.

I’m Aditya. I review PRs every Tuesday and Thursday. Add me as a reviewer.

Pro tips:

If you don’t have a real good first issue yet, run Prompt 21 to generate one.
“I review PRs every Tuesday” is a public commitment. It will keep you honest.

Prompt 14 - The commit-history-as-narrative prompt

Purpose/context: Conventional Commits turned your commit log into a feature inventory. This prompt turns it back into a story. Recruiters who click “Commits” expect a story, not a feature list. Pull quotes from your own commit messages are 10× more credible than fabricated stats.

The prompt:

You are turning a Conventional Commits log into a 5-sentence narrative paragraph.

Project: [YOUR PROJECT]
Paste your last 30 commit messages (Conventional Commits format):
[PASTE HERE]

Output:
- A 5-sentence paragraph that narrates the project's arc:
  S1: The first commit and what the project was originally scoped to do.
  S2: The first major pivot or scope change.
  S3: The hardest bug, named from a `fix:` commit.
  S4: The most interesting `feat:` and what it unlocked.
  S5: Where the project is now and what the next commit probably is.

Constraints:
- Quote 3 commit messages verbatim (in backticks).
- No fabricated stats. If you don't know the time spent, say so.
- The arc must match the actual commit history.

Example output:

The repo started with feat: initial commit of csv reader, scoped as a 100-line script. The first pivot came in refactor: switch to streaming csv reader for large files, which was forced by an issue from a user with a 4GB export. The hardest bug was fix: handle BOM marker in UTF-8 CSVs - a single byte that broke the first row. The most interesting feature was feat: add type inference with 1000-row sample, which unlocked every downstream SQL dialect. The next commit is probably a feat: for Parquet support, which is the issue with the most thumbs-up.

Pro tips:

Run this prompt every quarter. The story should change as the project grows.
Quote real commit SHAs in the README. A clickable link to the commit is gold.

Prompt 15 - The “alternatives considered” table

Purpose/context: A “Why not just use X?” section is the most senior-engineer move a junior README can make. It also helps the project rank for “[your tool] vs [alternative]” searches, which is high-intent AEO territory.

The prompt:

You are writing an "Alternatives considered" section for a GitHub README.

Project: [YOUR PROJECT]
Top 3 alternatives I considered before building this:
1. [name + 1-line description]
2. [name + 1-line description]
3. [name + 1-line description]

For each, output:
- Why I didn't pick it (specific reason, not a generic con).
- The single use case where that alternative IS better than mine.
- A markdown table row I can paste directly into the README.

Then output a 3-sentence paragraph explaining how I picked the boundary between "use mine" and "use theirs."

Constraints:
- Be respectful to the alternatives.
- No "X is bad" - name the trade-off, not the verdict.
- The table must be markdown, not ASCII art.

Example output:

Tool	Why I didn’t pick it	When it’s still better
`csvsql` from csvkit	Outputs SQL only as a query, not a file of `INSERT` statements	Ad-hoc querying in a one-off SQLite session
Pandas `to_sql`	Loads the whole CSV into memory	In-process Python pipelines under 100MB
`pgloader`	Requires a running Postgres target	Production data migration with a live DB

I built csv2sql for the narrow case where you have a CSV, no live database, and a SQL file you want to paste later. If you have a live database, pgloader is the right tool.

Pro tips:

This table is great for SEO. People search “csv2sql vs csvkit” and land here.
Update the table every 6 months. Tooling moves fast.

SECTION 4: Stack & architecture prompts (prompts 16–20)

Recruiters and senior interviewers will look at the code, not the screenshots. The next five prompts make the code visible in the README without dumping the whole repo.

Prompt 16 - The “Tech stack with intent” badge block

Purpose/context: Most READMs have a Shields.io badge block that lists the stack without context. Recruiters want to know why each tool, not just what it is. This prompt upgrades the badge block into a “stack with intent” section.

The prompt:

You are upgrading a README's tech-stack badge block.

Project: [YOUR PROJECT]
Stack (paste a list of tools, e.g., Python 3.12, FastAPI, Click, Pytest, SQLite):
[PASTE]

For each tool, output:
1. A Shields.io badge markdown line.
2. A 1-sentence note on WHY this tool (not just what it is).

Constraints:
- Use shields.io endpoint format: ![Name](https://img.shields.io/badge/...)
- Keep the "why" sentence to 12 words.
- Group the badges under 3 H3s: "Language", "Framework", "Tooling".
- Total stack <= 12 badges.

Example output:

Language

- Picked for the stdlib csv and sqlite3 modules.

Framework

- Async REST surface, no extra ORM.

Tooling

- Table-driven tests, runs in 4 seconds.

Pro tips:

A “why” sentence per badge is the difference between a junior and senior README. Senior engineers always have a reason.
Keep the badge count under 12. More than that and the page looks like a fruit salad.

Prompt 17 - The “How it works in 30 seconds” 4-bullet section

Purpose/context: A “How it works” section with 4 short bullets beats a 500-word architecture essay. Recruiters want to skim. This prompt distills the architecture into 4 bullets that a non-dev can follow.

The prompt:

You are writing a "How it works" section for a GitHub README.

Project: [YOUR PROJECT]
Architecture in one sentence: [paste]
The 4 most important moving parts:
1. [paste]
2. [paste]
3. [paste]
4. [paste]

Output 4 bullets, each following this template:
- **Name**: 1 verb-phrase on what it does + 1 phrase on why it matters.

Constraints:
- Each bullet <= 22 words.
- No "and then" - pick a verb per bullet.
- The 4 bullets should, in order, walk through the data flow.

Example output:

Reader: Streams the CSV in 8KB chunks, so a 4GB file uses about 30MB of RAM.

Type inferer: Samples 1,000 rows to pick INTEGER, TEXT, or TIMESTAMP per column.

SQL emitter: Batches 500 inserts per INSERT INTO ... VALUES (...) statement for speed.

CLI: Wraps all three in a single command with --infer and --output flags.

Pro tips:

The verb-phrase is the key. “Streams the CSV” beats “handles the CSV.”
If you can’t write 4 bullets, your project is too small to ship as a public repo. That’s fine - keep it private and ship something bigger.

Prompt 18 - The Mermaid sequence diagram for the “magic moment”

Purpose/context: A sequence diagram shows interactions between components. It’s the perfect follow-up to the flowchart in Prompt 8. Together they answer “what is the system” and “what happens when a user clicks run.” Mermaid.js sequence diagrams render natively on GitHub.

The prompt:

You are writing a Mermaid sequence diagram for a GitHub README.

Project: [YOUR PROJECT]
The "magic moment" user action: [paste]
The 3–5 components involved: [paste list]
What each component returns to the next: [paste]

Output:
1. A `sequenceDiagram` Mermaid block.
2. A 2-sentence paragraph below explaining the happy path.
3. A 1-sentence "what could go wrong" note that points to the error-handling code.

Constraints:
- Max 5 participants.
- Use `Note over` for the user-visible milestone.
- Keep messages short (max 6 words each).

Example output:

```mermaid
sequenceDiagram
  participant U as User
  participant CLI
  participant P as Parser
  participant E as Emitter
  U->>CLI: csv2sql big.csv --infer
  CLI->>P: stream rows
  P-->>CLI: typed rows
  CLI->>E: batched inserts
  E-->>U: out.sql
```

Happy path: the user runs one command and gets a SQL file. If the CSV has mixed line endings, the parser falls back to python-sniffer - see src/parser.py:42 for the branch.

Pro tips:

Sequence diagrams are an underrated way to show that you understand async, retries, and error handling.
Clickable links to source code (src/parser.py:42) are gold. Recruiters will follow them.

Prompt 19 - The “Performance” section with honest numbers

Purpose/context: A performance section with real numbers is the single highest-credibility section in a README. Even one benchmark separates you from 95% of junior repos. This prompt writes the section without fabricating data.

The prompt:

You are writing a "Performance" section for a GitHub README.

Project: [YOUR PROJECT]
Hardware you ran benchmarks on: [paste]
Dataset shape: [paste]
Results (paste the real numbers you actually measured):
- [paste]
- [paste]
- [paste]

Output:
- A markdown table with columns: Dataset | Rows | Wall time | Peak RAM.
- A 2-sentence paragraph on the bottleneck and what you'd optimize next.
- The exact command to reproduce the benchmark.

Constraints:
- Use only real numbers. Mark estimated rows in italics.
- Wall time to 1 decimal place (e.g., 11.3s, not "about 11 seconds").
- The reproduction command must be one line and copy-pasteable.

Example output:

Dataset	Rows	Wall time	Peak RAM
small.csv	1,000	0.04s	18 MB
medium.csv	50,000	1.2s	22 MB
big.csv	1,200,000	38.4s	30 MB

The bottleneck is disk I/O on the writer. Next I’d add a --buffer-mb flag to tune the write batch size. Reproduce with: python bench/run_bench.py.

Pro tips:

Real numbers > big numbers. “1.2s for 50,000 rows” is more credible than “blazing fast.”
The “what I’d optimize next” sentence is the cheapest way to signal senior thinking.

Prompt 20 - The “Trade-offs I accepted” table

Purpose/context: Engineering is the art of trade-offs, not the art of perfection. A trade-offs table is a senior-engineer move that takes 10 minutes and pays off in every interview. It pairs well with the “Why not X” table from Prompt 15.

The prompt:

You are writing a "Trade-offs I accepted" section for a GitHub README.

Project: [YOUR PROJECT]
Top 4 decisions where I picked one option over another:
1. [paste decision + 2 options]
2. [paste]
3. [paste]
4. [paste]

For each, output a markdown table row:
| Decision | Picked | Rejected | Why I picked it | The cost I accepted |

Constraints:
- Be specific. "Picked SQLite over Postgres" beats "Picked a database."
- The cost column must be honest. No "none."
- 4 rows max.

Example output:

Decision	Picked	Rejected	Why I picked it	The cost I accepted
Database	SQLite	Postgres	Zero-config install, single-file DB	No concurrent writers, no JSONB
CLI parser	Click	Typer	Smaller dep tree, broader docs	More boilerplate per command
Tests	Pytest	unittest	Fixtures, parametrize, faster	Extra 1 dependency
Docs	MkDocs	Docusaurus	Lighter, no Node toolchain	Fewer ready-made themes

Pro tips:

This is also the section to update if you ever reverse a decision. Update it in the same commit.
Senior engineers love this table. Recruiters forwarding to hiring managers love it too.

SECTION 5: Contributing & community prompts (prompts 21–25)

Open-source is a community activity. These five prompts turn your repo from “code on GitHub” to “a place people want to help.”

Prompt 21 - A `good first issue` generator

Purpose/context: A good first issue label is the single most effective tool for converting lurkers into contributors. Octoverse 2024 reported that “1.4 million new developers globally joined open source” in 2024, and many of them started on labeled beginner issues (Octoverse 2024). If you don’t have one, you’re losing them.

The prompt:

You are writing 3 GitHub issues for a repository, each labeled `good first issue`.

Project: [YOUR PROJECT]
Stack: [paste]
Easiest file a new contributor could touch: [paste file path]
A real bug or feature gap a junior could fix in under 2 hours:
[paste]

For each issue, output:
- Title (<= 60 chars, starts with a verb).
- Body, formatted as:
  ## Summary
  (1 sentence)
  ## Why
  (1 sentence on user impact)
  ## Steps to reproduce / Acceptance criteria
  (3–5 bullets)
  ## Files to look at
  (1–3 paths)
  ## How to test
  (1 command)
- 3–5 labels (e.g., good first issue, help wanted, docs).
- An estimate of time to first PR (e.g., "~90 minutes for a first-time contributor").

Constraints:
- No "fix the bug" titles. Name the bug.
- Each issue should be solvable in a single PR.
- The "Why" must reference a real user outcome, not a maintainer preference.

Example output:

Title: Add a --dry-run flag to the CLI

Body:

Summary

Users currently cannot preview the SQL output before writing a file.

Why

First-time users are afraid of overwriting an existing out.sql in the wrong directory.

Steps to reproduce / Acceptance criteria

Add a --dry-run flag to the CLI parser.

When set, the emitter prints the first 10 statements to stdout and exits.

Existing tests still pass.

A new test covers the flag’s stdout-only behavior.

README’s “Quick start” gets one new line.

Files to look at

src/cli.py

src/emitter.py

How to test

pytest tests/test_cli.py -k dry_run

Labels: good first issue, help wanted, cli, enhancement Time to first PR: ~90 minutes

Pro tips:

The “time to first PR” estimate is the most-skipped field. Add it. It calibrates expectations.
Pin the issue in the repo. Make it the front door.

Prompt 22 - A `CONTRIBUTING.md` that doesn’t shame newbies

Purpose/context: A CONTRIBUTING.md is a forcing function for “how do I run this repo locally?” The Open Source Guides recommend it as one of the four files every new project must have. Most junior CONTRIBUTING.md files are copy-pasted from big projects and don’t apply to a 600-line side project.

The prompt:

You are writing a CONTRIBUTING.md for a small (< 1000 LOC) GitHub repo.

Project: [YOUR PROJECT]
Stack: [paste]
Setup command: [paste the exact command]
Test command: [paste]
Lint command: [paste]
Conventional Commits required? [yes/no]
Pull request template? [yes/no]

Output a CONTRIBUTING.md with these sections, in this order:
1. Welcome (1 paragraph, first-person).
2. Local setup (3 numbered steps).
3. Running tests (1 command + 1 line on how to add a test).
4. Coding style (max 6 bullets).
5. Commit messages (link to Conventional Commits if yes).
6. Opening a PR (5 bullets, no corporate jargon).
7. Filing an issue (3 bullets, no shaming).
8. Maintainer commitments (your name + when you review).

Constraints:
- < 80 lines total.
- No "please ensure" or "kindly" filler.
- The PR section should mention the smallest possible PR.

Example output (excerpt):

Welcome

Hey - I’m Aditya, the maintainer. If you’ve never contributed to open source, this repo is a good place to start. The codebase is small and I review PRs every Tuesday and Thursday.

Local setup

Clone the repo.

Run make setup (or pip install -e .[dev]).

Run make test to confirm everything works.

Opening a PR

Smallest possible PR. One issue, one fix, one test.

Title in Conventional Commits format.

Link the issue with Closes #N.

Expect a review within 48 hours.

If I don’t respond in a week, ping me on the issue.

Pro tips:

“I review PRs every Tuesday and Thursday” is a public commitment. It will keep you honest.
The “smallest possible PR” rule cuts review time in half.

Prompt 23 - A `CODE_OF_CONDUCT.md` with teeth

Purpose/context: A code of conduct is the Open Source Guides’ recommended fourth file. Most junior projects skip it. The Contributor Covenant is the de-facto standard and used by Kubernetes, Rails, Swift, and tens of thousands of other projects. The prompt adapts the Covenant for a tiny project.

The prompt:

You are writing a CODE_OF_CONDUCT.md for a small GitHub repo.

Project: [YOUR PROJECT]
Maintainer name: [paste]
Maintainer contact: [email or GitHub handle]
Project size: [solo maintainer / 2-3 contributors / 10+ contributors]

Output a CODE_OF_CONDUCT.md based on the Contributor Covenant, adapted for a small project:
- Keep the 4 sections of the Covenant (Purpose, Pledge, Standards, Enforcement).
- Add a 5th section: "How to file a report" with your actual contact.
- Replace the "Slack / Discord" references with a link to GitHub Discussions, since small projects rarely have chat.
- Cut the section on "scope of facilities" - small repos don't have facilities.

Constraints:
- Use the Contributor Covenant 2.1 wording for the Pledge.
- Under 80 lines.

Example output (excerpt):

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.

Pro tips:

Use Contributor Covenant 2.1. It is the most-recognized standard.
If you don’t have a project email, use a GitHub issue with a private maintainer-only label.

Prompt 24 - A “How to ask a question” README section

Purpose/context: Most junior maintainers get the same 5 questions over and over. A “How to ask a question” section cuts questions by 50% and gets better answers when they do come. It is also a strong signal to recruiters that you operate like a professional maintainer.

The prompt:

You are writing a "How to ask a question" section for a GitHub README.

Project: [YOUR PROJECT]
Where questions should go: [GitHub Discussions / GitHub Issues / Discord / Stack Overflow]
Response time commitment: [paste]
The 3 most common questions you get: [paste list]

Output:
1. A 4-sentence paragraph on where to ask and what to include.
2. A "good question" template with 4 prompts:
   - What are you trying to do?
   - What have you tried?
   - What did you expect to happen?
   - What actually happened? (paste error text, link screenshots)
3. A short list of questions that should NOT go in the issue tracker (e.g., "How do I learn Python?").

Constraints:
- The template must be copy-pasteable.
- The "do not ask" list should be polite but specific.
- Under 60 lines.

Example output (excerpt):

Asking a good question

**What are you trying to do?**
(e.g., convert a 4GB CSV to PostgreSQL inserts)

**What have you tried?**
(e.g., `csv2sql big.csv --output out.sql`)

**What did you expect?**
(e.g., a SQL file under 30 seconds)

**What actually happened?**
(paste the error text and the last 20 lines of `out.sql`)

Pro tips:

The 4-prompt template is from Open Source Guides’ How to Contribute. It is the single best template I’ve seen.
Pin the “How to ask a question” section to the Discussions page if you use them.

Prompt 25 - A “Maintainer log” / changelog story

Purpose/context: A maintainer log is the human voice of a Keep a Changelog file. It tells the story behind each release. Recruiters who click “Releases” love it because it shows that you communicate.

The prompt:

You are writing a maintainer log / changelog for a GitHub repo's Releases page.

Project: [YOUR PROJECT]
Last 3 release versions: [paste]
The biggest user-visible change in each: [paste]
The smallest change you are most proud of in each: [paste]

Output 3 release notes in this format:

## vX.Y.Z - YYYY-MM-DD

### Headline
(1 sentence, 1 verb, 1 outcome)

### What changed
- (3–6 bullets, user-visible, no internal refactors)

### What I learned
- (1 sentence, first-person, trade-off or surprise)

### Thanks
- (1 line, name a contributor if any)

Constraints:
- Past tense for "what changed," first-person for "what I learned."
- 200 words max per release.
- No "bug fixes and improvements" filler - name the bug.

Example output (excerpt):

v0.4.0 - 2026-04-12

Headline

Added --dry-run so users can preview SQL output without writing a file.

What changed

New --dry-run flag prints the first 10 statements to stdout.

csv.Dialect is now detected per file, not per run.

README’s “Quick start” now shows the new flag.

What I learned

Adding the flag was a 30-line change, but writing the docstring for it took longer than the code.

Thanks

Thanks to @maria-p for the original feature request.

Pro tips:

“What I learned” is the single most-credible release note sentence. Recruiters read it.
Naming a contributor in “Thanks” pulls in repeat contributions. It is the cheapest retention trick in open source.

SECTION 6: Profile-README & showcase prompts (prompts 26–30)

Your github.com/username page is the cover of the book. The last five prompts handle the profile README, the pinned repos, the “now playing / building” section, and the cross-link to your LinkedIn.

Prompt 26 - The profile README hero paragraph

Purpose/context: A profile README is the special repo named after your username. It is the front door of your GitHub identity. Most junior profile READMs are a wall of badges. This prompt writes a hero paragraph that reads like a personal site.

The prompt:

You are writing a GitHub profile README (the repo named after the username).

Username: [paste]
One-line role: [e.g., "Junior backend engineer learning systems design"]
Currently working on: [paste]
Currently learning: [paste]
How to reach me: [paste]
Top 3 pinned repos: [paste list with 1-line descriptions]

Output:
- A 1-sentence tagline (max 12 words).
- A 3-sentence "About me" paragraph.
- A 4-bullet "Currently" section (working on / learning / reading / listening).
- A 4-bullet "Pinned work" list with 1-line descriptions.
- A "📫 Reach me" line with 2 channels.

Constraints:
- No "passionate", "driven", "enthusiast".
- The "Currently" section must be timestamped ("as of June 2026").
- Keep the whole README under 60 lines.

Example output:

Aditya Mallah

Backend engineer in training, building small tools to learn distributed systems.

I write Python and Go in the evenings and ship one side project a month. Most of my repos are small on purpose - I learn more from a 600-line tool than a 60,000-line one. I’m looking for a junior backend role where I can keep learning.

Currently (as of June 2026):

🔨 Building: a CSV-to-SQL CLI with streaming reads.

📚 Learning: Postgres internals and EXPLAIN ANALYZE.

🎧 Listening: the Backend Banter podcast.

📌 Pinned: csv2sql, dotfiles, a-little-renderer, blog

📫 Reach me: GitHub Discussions, or @adityamallah on LinkedIn.

Pro tips:

“As of June 2026” is the credibility stamp. Recruiters want to know the profile is alive.
The “I’m looking for a junior backend role” line is a recruiter magnet. State it plainly.

Purpose/context: A banner image at the top of a profile README makes the page feel like a portfolio site. The trick is to generate it with a consistent design system so the page looks like a brand, not a collage.

The prompt:

You are writing a prompt for an image-generation model (DALL-E, Midjourney, or Ideogram) to create a GitHub profile README banner.

Username: [paste]
Role: [paste]
Aesthetic: [paste - e.g., "low-contrast minimal, dark mode, single accent color"]
Accent color hex: [paste]
What the banner should show: [paste - e.g., "the username in a clean sans-serif, 2 small repo icons"]

Output:
- A 1500×500 banner image prompt (this is the standard GitHub README banner size).
- The prompt should specify:
  - Composition (rule of thirds, centered text).
  - Typography (font, weight, alignment).
  - Background (gradient, solid, or pattern).
  - Icons or shapes (max 3, no clip-art).
  - The single accent color and how it is used.

Constraints:
- No "in the style of [named artist]".
- No realistic faces.
- The username must be legible at 500px wide.
- Single accent color, max 2 background shades.

Example output:

A 1500×500 banner with a deep navy (#0d1117) background and a single thin diagonal line in mint (#3ddc97) crossing from bottom-left to top-right. The username “adityamallah” in a clean geometric sans-serif (Inter or Sora), 80pt, weight 600, left-aligned, white (#ffffff), placed 80px from the left edge. Three small filled circle icons in mint sit to the right of the username, evenly spaced. No gradients on text, no glow, no shadows.

Pro tips:

1500×500 is the GitHub-recommended banner ratio.
Regenerate until the username is legible. A pretty banner with unreadable text is worse than a plain one.

Prompt 28 - The “Pinned repos” caption generator

Purpose/context: GitHub shows up to 6 pinned repos on your profile. The pin’s description is the most-skipped field. This prompt writes 1-line descriptions that hook a recruiter.

The prompt:

You are writing 1-line descriptions for 6 pinned GitHub repos.

Username: [paste]
The 6 repos (paste names + 1-line technical summary):
[PASTE]

For each, output:
- A 1-line description (max 80 chars).
- The single most impressive metric, if any (stars, downloads, users, lines of code).
- A 1-line "what I'd add next" hint, if honest.

Constraints:
- Description starts with a verb or a noun, not "A tool for".
- The metric must be real, not aspirational.
- If the repo is private or has zero stars, skip the metric.

Example output:

csv2sql - A streaming Python CLI that turns CSVs into SQL inserts in seconds. 142 stars. Next: Parquet support.

dotfiles - Personal macOS setup, automated with make. 12 stars.

a-little-renderer - A 600-line software renderer in C, learning exercise. 8 stars. Next: texture mapping.

blog - Notes on Postgres, Go, and the junior dev job hunt. 0 stars - it’s new.

Pro tips:

The “what I’d add next” line is a great signal of momentum. Recruiters love a roadmap.
If a pinned repo has 0 stars, that’s fine. Repin it and write a description that explains the intent.

Purpose/context: A “Now” widget is a 1-paragraph section on your profile README that says what you’re working on this month. It’s a nownownow.com convention that signals activity. Recruiters and senior engineers check it.

The prompt:

You are writing a "Now" widget for a GitHub profile README.

Username: [paste]
Month + year: [paste]
Top 3 things you are working on this month:
1. [paste]
2. [paste]
3. [paste]

Output:
- A 1-paragraph "Now" section (3 sentences).
- A 4-bullet "Building / Learning / Reading / Shipping" block.
- A timestamp line ("Last updated: YYYY-MM-DD").

Constraints:
- Present continuous tense ("shipping", "learning", "reading").
- No "I am passionate about".
- Under 30 lines.

Example output:

Now (June 2026): I’m shipping a --dry-run flag for csv2sql, learning about Postgres MVCC, and reading Designing Data-Intensive Applications a second time. I’m also writing 1 blog post a week.

🔨 Building: csv2sql v0.5.0 with a --dry-run flag.

📚 Learning: Postgres MVCC and EXPLAIN ANALYZE.

📖 Reading: Designing Data-Intensive Applications (2nd pass).

🚢 Shipping: 1 blog post a week, Sundays.

Pro tips:

Update the “Now” section on the 1st of every month. Set a calendar reminder.
“Last updated” is a credibility stamp. Recruiters check it.

Prompt 30 - The “Cross-link” CTA at the bottom of the profile README

Purpose/context: A profile README that ends with a single line linking to your LinkedIn / personal site / blog is the single highest-ROI move for a junior job hunt. The prompt writes that line and a 2-line “how to reach me” footer.

The prompt:

You are writing the final footer of a GitHub profile README.

Username: [paste]
The 2 best ways to reach you: [paste]
The 1 best link a recruiter should click: [paste]

Output:
- A 1-line CTA ending with a verb and a link.
- A 2-line "How to reach me" block with channel names, not usernames.
- A 1-line "If you fork this profile README, give me a star" line (optional, only if friendly tone).

Constraints:
- The CTA uses second person ("If you're hiring, ...").
- No email addresses (use GitHub or LinkedIn).
- Under 8 lines total.

Example output:

👋 If you’re hiring a junior backend engineer, open an issue - I read every one.

How to reach me: GitHub Issues (best) · LinkedIn DM (good)

If you forked this profile README to copy the structure, a ⭐ to the original is appreciated.

Pro tips:

“Open an issue” is the lowest-friction way for a recruiter to contact you. Lower than email.
The “if you forked this, star the original” line only works for popular profile templates. Skip it for personal profiles.

Comparison table: prompt categories vs. README section vs. output

This is the cheat sheet. Tape it to your monitor.

#	Prompt category	README section it fills	Output format	Recruiter signal
1	Project pitch (1–5)	Hero + Why	3 lines, pull-quote, GIF caption	”I can write.”
2	Demo & screenshots (6–10)	Demo / visuals	GIF script, alt text, Mermaid block	”I can show, not just tell.”
3	Story & context (11–15)	Why this exists, lessons	5-sentence narrative, trade-off table	”I can learn and reflect.”
4	Stack & architecture (16–20)	Architecture, performance	Badge block, sequence diagram, perf table	”I can build, not just glue.”
5	Contributing & community (21–25)	Issues, CONTRIBUTING, CoC	Issue body, contributing guide, release notes	”I can collaborate.”
6	Profile & showcase (26–30)	github.com/username page	Hero paragraph, banner, “Now” widget	”I can be a teammate.”

The order is also the order you should write a README in: hero first, demo second, story third, stack fourth, community fifth, profile last.

A 14-day “5 repos” sprint

The prompts are useless without a plan. Here is the 14-day sprint I recommend. It produces 5 portfolio repos with story READMEs, in 2 weeks, at 1–2 hours a day.

Days 1–2: Pick the 5 repos.

1 large repo (the side project you’re most proud of)
1 small repo (a weekend hack, < 500 LOC)
1 docs-only repo (a learning-python notes folder you already have)
1 tutorial clone (you rebuilt a tutorial, with your own twist)
1 “weird” repo (an experiment, a renderer, a chatbot, anything that signals curiosity)

For each, run Prompt 1 (hero) and Prompt 2 (problem → solution → outcome) and paste the outputs into a Google Doc.

Days 3–5: Write the 4-part anatomy.

For each of the 5 repos, write the 4 sections from the anatomy in section 2 of this guide. Use Prompt 11 (lessons learned) and Prompt 12 (what I would NOT recommend) for the 2 senior-engineer moves. Don’t run more than 2 prompts per repo per day; you want time to rewrite in your own voice.

Days 6–7: Visuals.

For each repo, capture one screenshot or one terminal GIF using the scripts from Prompts 6, 9, and 10. Crop, alt-text, caption. Day 7 is also when you generate the Mermaid diagrams for the 2 repos where it makes sense (Prompts 8 and 18).

Days 8–9: Stack & performance.

Run Prompt 16 (badge block), Prompt 17 (how it works), and Prompt 19 (performance) on the large repo. Real numbers only.

Days 10–11: Community.

For the large repo, run Prompt 21 (good first issue), Prompt 22 (CONTRIBUTING), and Prompt 24 (how to ask a question). Pin the good-first-issue.

Days 12–13: Profile README.

Run Prompts 26–30 in order. Update the “Now” widget, the banner, the pinned captions, the cross-link footer.

Day 14: Ship and announce.

Commit every README with a docs(readme): ... Conventional Commits message.
Post 1 of the 5 repos on Hacker News or r/programming.
DM 3 senior engineers on LinkedIn with a 2-sentence pitch.
Update your profile README with the date you shipped.

If you do this, by day 15 you have a portfolio that reads like a developer’s personal site, not a code dump. That is the difference.

Common mistakes to avoid

I have read a few thousand junior READMs at this point. Here are the mistakes that show up over and over.

Mistake 1: The README is a manual. The first 3 lines should sell, not instruct. Move install instructions to H2 #2 or later.

Mistake 2: No hero GIF. Recruiters skim. A still README with a wall of text reads as “low effort.” A 15-second GIF (Prompt 6) takes an hour and pays off forever.

Mistake 3: Badges with no intent. A badge block that says Python 3.12 without a “why” sentence (Prompt 16) is a missed opportunity. Name the trade-off.

Mistake 4: A “Contributing” line that says “Pull requests welcome.” That’s not a contributing guide. Run Prompt 22 and write a real one. The Open Source Guides call it one of the four essential files (Open Source Guides).

Mistake 5: No code-of-conduct link. The Contributor Covenant is the standard. Add it. Takes 10 minutes.

Mistake 6: Commit messages that don’t follow Conventional Commits. A commit log is a portfolio too. Adopt the spec on day one (Conventional Commits 1.0.0).

Mistake 7: A “Future” section with 12 checkboxes that never get checked. Either ship them or cut them. An unchecked roadmap is a credibility tax.

Mistake 8: No “Now” widget. The nownownow.com convention signals activity. Update it on the 1st of every month.

Mistake 9: “This project is in active development.” If it’s not actively developed, archive the repo. Don’t lie.

Mistake 10: A README written entirely by ChatGPT. The prompts are scaffolds, not scripts. Your voice is the product.

Final word

The README is the cheapest, highest-ROI artifact in your developer portfolio. It costs you an afternoon. It works for every job you apply to, forever. And in 2026, with 180 million developers on GitHub (GitHub Press, Oct 30 2025) and 1.4 million new open-source contributors joining in 2024 alone (Octoverse 2024), a story README is the single sharpest way to stand out.

Pick one repo. Run Prompt 1. Run Prompt 2. Run Prompt 6. Ship it. Repeat.

The hardest part of any GitHub README is not writing it. It is caring enough to rewrite it. You have 30 prompts now. The rest is on you.

If this helped, open an issue on our GitHub. If it didn’t, open an issue anyway. We read every one.

Reader disclosure & educational-purpose notice

This page is published by SuperFreshAI for general informational and educational purposes only. By reading it, you agree to the points below.

Editorial independence. All reviews, guides, and recommendations are written by our editorial team based on hands-on use. Some links on this site are affiliate links, and some articles are produced as partner content — both are always clearly labeled. Our editorial conclusions are never shaped by partners or affiliates.
Not professional advice. Nothing on this page constitutes legal, financial, medical, tax, or other professional advice. AI tools, pricing, and capabilities change quickly — always verify current information with the tool's official documentation before making a decision.
Educational purpose only. The content here is intended to help you learn about AI tools and workflows. It is not a guarantee of results, performance, fitness for a particular purpose, or suitability for your specific situation. Your results may vary.
No warranties. The site and its content are provided on an "as is" and "as available" basis. We make no warranties, express or implied, about accuracy, completeness, reliability, or availability. See our Terms and Privacy for the full legal terms.
Your responsibility. You are responsible for how you use the information on this page, including any decisions you make based on it. Always do your own research and consult a qualified professional when appropriate.
Affiliate & partner disclosure. When you click certain outbound links, we may earn a commission at no extra cost to you. When a piece of content is produced as partner content, it is labeled at the top of the page. See our Editorial Policy for the full standards we follow.

By continuing to read, you acknowledge that you have read and understood this notice.

30 ChatGPT prompts for junior developers to build GitHub README stories

Quick answer (read this first)

Why your README looks like an instruction manual (with a 2026 stat)

The 4-part README story anatomy

SECTION 1: Project-pitch prompts (prompts 1–5)

Prompt 1 - The 3-line hero paragraph

Prompt 2 - Problem → Solution → Outcome narrative

Prompt 3 - The elevator pitch from a job-description lens

Prompt 4 - The “Who is this for / not for” honesty section

Prompt 5 - The TL;DR box that doubles as a hero GIF caption

SECTION 2: Demo & screenshot prompts (prompts 6–10)

Prompt 6 - A 15-second hero GIF script

Prompt 7 - Screenshot alt text and caption generator

Prompt 8 - Mermaid.js architecture diagram from a code walkthrough

Prompt 9 - A terminal capture that shows the “magic moment”

Prompt 10 - A “before / after” comparison screenshot prompt

SECTION 3: Story & context prompts (prompts 11–15)

Prompt 11 - The “lessons learned” paragraph

Prompt 12 - The “what I would NOT recommend” honesty paragraph

Prompt 13 - The “this is for the next junior dev” letter

Prompt 14 - The commit-history-as-narrative prompt

Prompt 15 - The “alternatives considered” table

SECTION 4: Stack & architecture prompts (prompts 16–20)

Prompt 16 - The “Tech stack with intent” badge block

Language

Framework

Tooling

Prompt 17 - The “How it works in 30 seconds” 4-bullet section

Prompt 18 - The Mermaid sequence diagram for the “magic moment”

Prompt 19 - The “Performance” section with honest numbers

Prompt 20 - The “Trade-offs I accepted” table

SECTION 5: Contributing & community prompts (prompts 21–25)

Prompt 21 - A good first issue generator

Summary

Why

Steps to reproduce / Acceptance criteria

Files to look at

How to test

Prompt 22 - A CONTRIBUTING.md that doesn’t shame newbies

Welcome

Local setup

Opening a PR

Prompt 23 - A CODE_OF_CONDUCT.md with teeth

Enforcement

Prompt 24 - A “How to ask a question” README section

Asking a good question

Prompt 25 - A “Maintainer log” / changelog story

v0.4.0 - 2026-04-12

Headline

What changed

What I learned

Thanks

SECTION 6: Profile-README & showcase prompts (prompts 26–30)

Prompt 26 - The profile README hero paragraph

Aditya Mallah

Prompt 27 - The profile README banner image prompt

Prompt 28 - The “Pinned repos” caption generator

Prompt 29 - The “Now” widget generator

Prompt 30 - The “Cross-link” CTA at the bottom of the profile README

Comparison table: prompt categories vs. README section vs. output

People Also Ask (FAQ, AEO-tuned)

1. How long should a junior developer’s GitHub README be in 2026?

2. Do GitHub stars actually matter for junior dev hiring in 2026?

3. What’s the single biggest mistake junior devs make in their README?

4. Should I use ChatGPT to write my whole README?

5. Is the Conventional Commits spec required for a portfolio project?

6. How do I get my first 10 stars as a junior dev?

7. Should I make my portfolio repos public or private?

8. What’s the best free tool to render a Mermaid.js diagram in my README?

9. How often should I update my README?

10. Can a great README actually get me a job in 2026?

A 14-day “5 repos” sprint

Common mistakes to avoid

Final word

SuperFresh AI

43 ChatGPT prompts for non-native English speakers to polish interview answers

41 ChatGPT prompts for SaaS founders in San Francisco to map local partnership opportunities

How to Detect AI-Generated Content

What Is the Best AI Tool for Writing?

AI Newsletter Writing Guide

Prompt 21 - A `good first issue` generator

Prompt 22 - A `CONTRIBUTING.md` that doesn’t shame newbies

Prompt 23 - A `CODE_OF_CONDUCT.md` with teeth