realroc/githire

GitHire

A workflow for shipping real production work with AI agents, organized so the human stays the decision-maker even when the AI writes most of the code.

---

Thesis

Stop assisting. Start operating.

AI coding speed already outruns human review speed. Reviewing code after it's written is too late. The unit of work shifts:

• Humans frame — write the issue, set constraints, declare non-goals, define success criteria.
• AI executes — generates the code, runs tests, opens the PR.
• Architects verify — make the final tradeoff before merge.

The six steps below place each role at the right point in the pipeline.

---

Canonical sources

When network access is available, the live site is the source of truth:

1. Homepage (current method) — https://realroc.github.io/git-hired/
2. Real production case — a 22-line SCAN+HGETALL incident, walked along all 6 steps — https://realroc.github.io/git-hired/case-redis-scan.html
3. Blog / field notes — https://realroc.github.io/git-hired/blog.html

If browsing is unavailable, references/method.md is the offline fallback. If the live site and the fallback disagree, prefer the live site and flag the drift briefly.

---

The six steps

1. Issue · Frame the problem

The issue is a contract between human and AI. Use the Prompt Spec template (below). Each missing section is an entry point for incidents.

2. Sandbox · Persistent dev environment

Not a fresh container per run. Real dependencies, real data shapes, real call volumes. If your test fixtures have 3 rows and production has 30,000, the sandbox is hiding the bug.

3. Execute · AI does the writing

Claude Code or Codex implements in the sandbox. The AI proposes design and code; the human reads the diff. Don't try to prescribe every line in the issue — that's micromanagement, not framing.

4. AI Review · Second agent, different priors

An independent reviewer agent with a different mandate: performance patterns, security patterns, anti-patterns. Not "rerun the tests" — a different lens. Cover what the first agent wasn't asked about.

5. Architect · Where humans decide ★

The most expensive 30 seconds in the workflow. The architect brings context the AI lacks: production QPS, capacity curves, prior incidents, team conventions. Mandatory questions:

• Is this hot path or cold path?
• What's the data scale today, in 6 months?
• Have we tried this before, and why didn't it work?
• Is this a one-way door (irreversible)?

If you only adopt one step from this workflow, adopt this one.

6. Production · Ship and leave a trail

Merge, deploy, write back to the issue. The issue + PR + AI-review notes + architect decision + handoff note is the durable memory of the call.

---

Prompt Spec template

Use this as the issue body, not a bare "I want X" sentence. Each missing section maps directly to a failure mode (see "Real failure mode" below).

## Goal
What we're trying to achieve, in user-visible terms.

## Constraints
Hard limits: call frequency, data scale, latency budget, existing schema we can't break.

## Non-goals
What this change must *not* do. Concrete anti-patterns (e.g. "no SCAN/KEYS in request-path code").

## Verification
How we'll know it's right: tests, smoke probes, production metrics that should/shouldn't move.

## Architecture notes
The shape we expect: data structures, index patterns, cache strategy. Architect can pre-bless or push back here.

## Existing context
Files most likely involved, prior decisions, related issues/PRs.

Real failure mode

A real production incident on 2026-05-14 (see case page) ran with this incoming prompt:

"国产模型判定走的是前缀匹配。我想做成 model_detail 里的 made_in_china 字段。"

It was missing:

| Section | What was missing | What broke | |---|---|---| | Constraints | call frequency, data scale | /api/site/config is hit every page load | | Non-goals | "no full-table SCAN" | AI used r.scan(match='model_detail::*') | | Architecture notes | use a maintained set, not runtime scan | AI built O(N) keyspace walk | | Verification | production p99 must not move | only smoke tests gated the merge |

Result: AI generated functionally-correct code in 5 minutes. Production was on fire 13 hours later. 25 hours of fix-chain commits until a Redis SET replaced the SCAN.

The 150 extra words the Prompt Spec asks for would have prevented all of it.

---

Agent behavior

• Start from a Prompt Spec, not a prompt. If the user gives you a vague request, draft Goal / Constraints / Non-goals / Verification first. Confirm those, then write code.
• Architect step is mandatory before merge. Never auto-merge AI-generated code without a human pause. If a human isn't reachable, slow down — don't substitute another AI for the architect.
• Leave a trail. Whatever the decision (merge, split, revert), write it back to the issue.
• Prefer the smallest reviewable PR. A 22-line PR is reviewable. A 1500-line PR is a rubber stamp.
• Cite the case when needed. Pointing at https://realroc.github.io/git-hired/case-redis-scan.html is faster than re-arguing why architect review exists.
• Ask only when it changes the plan. Surface assumptions; don't require permission for trivial calls.

---

Outputs the agent can produce

Issue brief (= Prompt Spec)

## Goal
## Constraints
## Non-goals
## Verification
## Architecture notes
## Existing context

PR plan

## Scope (in / out)
## Files likely involved
## Risks the architect should check
## Review checklist (perf / security / consistency)
## Rollout & rollback note

Architect review prompt

## What you're approving (one sentence)
## Hot path / cold path
## Data scale assumptions
## Reversibility (one-way door?)
## Decision (merge / revise / split / restart)

Handoff note

## What changed
## Why this path
## What was considered and rejected
## What to watch in the next 24h

Onboarding plan (hiring / first PR scenario)

## Candidate's first issue (Prompt-Spec'd)
## What signals we're reading from their PR
## Where the architect will gate
## What "good first PR" looks like for this team

---

Trigger phrases

Activate this skill when the user asks to:

• "frame this issue", "write a prompt for this", "convert to Prompt Spec"
• "review this AI-generated code", "architect pass on this PR"
• "onboard a new engineer", "first PR for a candidate", "hire through real PRs"
• "use GitHire", "GitHire methodology", "issue-first workflow", "AI-native workflow"

Also activate proactively when the user shows a vague prompt and asks for code: offer to convert it to a Prompt Spec first.

---

Don't

• Don't expand a vague prompt into code without showing the Prompt Spec first.
• Don't put SCAN / KEYS / unbounded loops in request-path code without a Non-goal explicitly permitting it.
• Don't skip the architect step because "AI review passed" — they cover different priors.
• Don't copy this method into the user's repo as boilerplate. Cite https://realroc.github.io/git-hired/ and let it stay live.