Why Your AI Backlog Tool Doesn't Know You're Building an iOS App

The App Icon That Would Have Gotten Rejected

We ran a backlog item through an AI refinement tool: “Design app icon.” Simple ticket. Should be easy. The AI came back with a polished set of acceptance criteria. One of them: “Export final icon as PNG with transparent background.”

That would have gotten the app rejected by Apple. iOS requires a 100% opaque icon background — transparent PNGs fail App Store review. It's not a minor edge case; it's day-one iOS knowledge. The AI had none of it, because the AI had no idea this was an iOS app.

That's the real problem with generic AI refinement. The output was technically coherent. It just wasn't yours.

The Context Problem

Most AI backlog tools treat every team as the same abstract “agile team.” Feed them a ticket, get back a template. The template is correct in the same way a horoscope is correct — vague enough to apply to anyone, specific enough to feel useful.

Solo founders get acceptance criteria written for designated team members. Mobile teams get assumptions baked for web. B2B enterprise tools get suggestions tuned for consumer apps. It's not that the AI is wrong. It's that the AI is answering a different question than the one you actually have.

The gap is context. And the painful irony is that the context already exists — it's sitting in your repo. Your package.json knows your stack. Your README.md describes what you're building. Your AGENTS.md or CLAUDE.md describes how your team works. None of it was being used.

The right acceptance criteria for “design app icon” on an iOS app is not the same as the right acceptance criteria for an Android app, a web app, or a desktop tool. The AI knows how to write acceptance criteria. It just needs to know which kind to write.

The Fix: Auto-Detection

Refine Backlog now auto-detects your project context before every refinement. No setup. No new files to create. No config to maintain.

When you run the CLI from your project directory, it reads context files in priority order:

• →AGENTS.md, CLAUDE.md, CODEX.md, GEMINI.md — AI instruction files
• →.github/copilot-instructions.md, .windsurfrules — IDE rules
• →llms.txt, README.md — project description
• →package.json — name, description, top 8 dependencies
• →prisma/schema.prisma — database schema hint

It combines up to 700 characters of context and passes it with every refinement request. If you already pass --context, auto-detection is skipped. You stay in control. The same auto-detection runs in the GitHub Action — every PR refinement is aware of your project. The website now has an optional context field too, for one-off sessions.

Before and After: Same Ticket, Different Output

Here's the same ticket refined twice — once with no context, once with iOS project context detected automatically:

Same ticket. Completely different output. The second set of criteria would pass App Store review. The first would not. The only difference is that the AI knew what it was building.

How It Works

Auto-detection reads files already committed to your repo. There is nothing new to create or configure. If you have a package.json, it reads the name, description, and top dependencies. If you have a README.md, it reads the first 300 characters. If you have AGENTS.md, it starts there.

The context is capped at 700 characters — enough to tell the AI what kind of project this is, what stack you're on, and how your team works. Not enough to slow the request or bloat the prompt. It logs exactly what it found:

You can pass --no-auto-context to disable it entirely, or --context "your text here" to override with something more specific.

One Workflow File. Your Repo. Your Context.

If you're already using the Refine Backlog GitHub Action, you get this for free on your next run. If you haven't set it up yet, it's one workflow file:

Every issue opened in your repo gets refined with the context of your actual project. No manual prompting. No context to maintain. Your repo already has everything the AI needs — now it reads it.