How to reverse-engineer Forge artifacts from an existing codebase. The goal is not to document what was built -- it's to produce a specification precise enough to rebuild the project from scratch, potentially in a different language or stack, and arrive at something architecturally faithful to the intent but likely better than the original.
Maturity note: BackForging applies a well-established reverse-engineering pattern (recovering a specification from a running system) using Forge's specific artifact templates. The underlying approach is the same as reverse-engineering a network topology from packet captures, recovering a protocol spec from observed traffic, or extracting an interface contract from a legacy codebase during a rewrite. The pattern is decades old and battle-tested across engineering disciplines. The specific Forge artifact templates (constitution, conventions, domain docs with Decided/Open, WHY blocks, TONIC tables) are newer and will refine through practice. The approach is sound. The templates will sharpen. If you BackForge a project and discover failure modes in the artifact structure, feed your findings back.
BackForging is the process of producing the Forge artifacts (constitution, conventions, domain docs, glossary, engineering plan) from a codebase that wasn't built with Forge. Once the spec exists, the code becomes disposable. The spec is the portable artifact. A PHP project BackForged into a proper spec could be rebuilt in Rust, Node, Go, or anything else without losing the architectural decisions.
This is not documentation. Documentation describes what was built. A Forge spec prescribes what must be built. The difference matters -- a BackForged spec is forward-looking, not backward-looking.
In a forward-Forged project, WHY blocks capture the reasoning at the moment of the decision. In a BackForged project, WHY blocks answer a different question:
Not: "Why did someone build it this way?" Instead: "Why should it continue to be this way?"
This is present justification, not historical reconstruction. Even if it's your own project from six months ago, you've forgotten most of the "why." The BackForging agent doesn't know either. Neither of you is doing archaeology. Both of you are evaluating whether each decision has a good reason to persist.
If a decision can be justified now -- it's a WHY block. If it can't be justified -- it's an Open Question for the rebuild. Maybe it was right at the time and circumstances changed. Maybe it was never right. Either way, the BackForging process surfaced it.
This is actually more valuable than forward WHY blocks in some cases. Forward WHY blocks can go stale. BackForged WHY blocks are written against current reality.
A session with large context reads the full codebase and produces draft Forge artifacts. If the codebase exceeds context limits, chunk it by domain boundary: prioritize entry points and public interfaces, summarize peripheral code. Each chunk produces draft artifacts for its domain.
- Constitution: What are the system's actual invariants? What architectural laws does the code enforce implicitly? (e.g., "all writes go through the API layer" -- is that true in practice or are there backdoors?)
- Conventions: What libraries are used? What patterns are followed? What naming conventions exist? What's the error handling strategy? These are extracted from the code itself, not imagined.
- Domain docs: What are the natural domain boundaries? What does each module/service/package do? What decisions are embedded in the code?
- Glossary: What terms does the codebase use? What do they mean in this project's context?
- Decision tracking: For each architectural decision the agent can identify, create a Decided entry with present-tense justification.
The agent's draft is a starting point. The human adds:
- WHY blocks the agent couldn't infer. The agent sees that Service A uses a message queue to talk to Service B but REST to talk to Service C. It can note the inconsistency but can't know if it's intentional. The human evaluates: is there a good reason? If yes, WHY block. If no, Open Question.
- Challenges to the agent's assumptions. The agent may identify patterns that aren't intentional -- they're just how it happened to evolve. The human decides which patterns are load-bearing architecture and which are accidental.
- Scope decisions. Is the BackForge for a full rebuild or a targeted refactor? What's in scope for the spec and what's out?
Run a cold validation session against the BackForged spec. But instead of asking "can you build this?", ask: "does this spec accurately describe the existing system?"
The cold session reads the spec and asks questions. But the evaluation is different:
- If the cold session's understanding of the spec matches the existing code's behavior -- the spec is accurate.
- If the cold session's understanding diverges from the code -- either the spec is wrong (fix it) or the code has a problem the spec should address (Open Question for the rebuild).
The most valuable output of BackForging is decisions that can't be justified now.
Every unjustifiable decision is one of:
- Accidental complexity -- it grew this way, nobody designed it, and it should be simplified in the rebuild
- Stale decision -- it was right once but circumstances changed (dependency deprecated, requirements shifted, better options exist now)
- Cargo cult -- copied from somewhere without understanding why, and nobody questioned it
- Genuine open question -- there might be a good reason but nobody currently in the room knows it
All four become Open Questions in the BackForged spec. The rebuild can address them consciously instead of inheriting them blindly.
The spec is ready when a cold session can read it and produce an architecture that matches the existing system's intent (not necessarily its implementation). The implementation details may change entirely in a rebuild -- different language, different libraries, different patterns. But the architectural decisions, the domain boundaries, the invariants, and the WHY blocks must be consistent.
Once the spec exists, rebuilding in a different stack is a matter of updating the conventions doc:
- BackForge the spec from the original codebase (Steps 1-5 above)
- Write a new conventions doc for the target stack (new language, new libraries, new patterns)
- Update TONIC entries -- the forbidden alternatives change when the ecosystem changes
- Run the normal Forge pipeline from Phase 4 onward (see
forge_process.md,cold_validation_protocol.md,cold_code_run_protocol.md)
The constitution and domain docs should need minimal changes -- they describe what the system does and why, not how. The conventions doc is where the stack-specific decisions live. Swap it out, and the cold code run produces the same architecture in a different language.
This is the portability argument for Forge: the spec is stack-independent. The code is generated from the spec. Change the conventions, regenerate the code.
Frontend code is harder to BackForge because the visual layer can't be fully captured in text. The spec doesn't try to describe what the interface looks like -- it specifies behavior and points at design artifacts.
For frontend BackForging:
- Reference the existing design artifacts -- CSS files, design tokens, component libraries, Figma docs, wireframes, screenshots. The spec says "use these" rather than trying to describe the visual in words.
- Focus on behavioral specification -- what happens on error, how keyboard navigation works, loading states, empty states, permission states, responsive breakpoints with specific behaviors. This is the territory covered by the UI/UX ambiguous language dictionary (see
../reference/). - Extract the interaction model -- not "the button is blue and 48px tall" but "on submit, validate all fields per Section 22 spec, show inline errors per Section 9 spec, disable the button and show a spinner during the request, re-enable on completion or error."
- Component inventory -- what components exist, what props they accept, what states they have. This is the domain doc equivalent for frontend.
The visual is the designer's job. The spec's job is everything the visual can't communicate.
The strongest temptation in BackForging is to describe the code: "UserService has methods createUser, getUser, updateUser, deleteUser." That's not a spec -- it's a summary. The spec says why the user service exists as a separate domain, why user creation goes through a specific validation pipeline, why soft-delete was chosen over hard-delete. Present justification, not code description.
Not every decision in the existing code deserves to survive. The BackForging process questions everything. If a decision can't be justified now, don't carry it forward as a Decided entry. Make it an Open Question that the rebuild addresses.
It's tempting to go straight from BackForged spec to rebuild. Don't. The cold validation step is what catches gaps between what you think the system does and what the spec actually says. Without it, the rebuild will surprise you.
BackForging is not a documentation project. The output is not a description of the existing system. It's a specification for rebuilding it -- one that's precise enough for a cold agent to execute. If the spec says "the auth service handles authentication," it's failed. That's documentation. A spec says "the AuthService validates JWT tokens using RS256, checks against a JWKS endpoint at {issuer}/.well-known/jwks.json, rejects tokens with exp in the past or iss not matching the configured issuer, and returns a 401 with body { error: 'INVALID_TOKEN', reason: '{specific_reason}' } on any failure."
This applies to any project with non-trivial business logic -- not just APIs and services, but anything where domain rules are encoded in code.
A codebase carries business logic decisions that nobody questions because they're buried in if statements, service methods, and workflow orchestration. The approval chain that requires three levels of sign-off. The pricing calculation that applies a discount only on Tuesdays. The rule that expires a session after 15 minutes but only for users in a specific tier. These are business decisions, not technical ones, but they live in code where only developers see them.
BackForging externalizes them. Every business rule becomes a Decided entry with a present-tense WHY block. Once they're visible and readable, the people who should be evaluating them -- product owners, business stakeholders, domain experts -- actually can. They can't read code. They can read "Decision 23: Session timeout is 15 minutes for free-tier users, 60 minutes for paid users. WHY: [can you justify this?]"
This is where BackForging becomes more than a technical exercise. It's a structured audit of every business rule in the system. The ones that can't be justified get flagged. The ones that are wrong get corrected before the rebuild bakes them in again. The ones that are right get documented so the next developer doesn't accidentally remove them.
If you're BackForging and you find yourself writing "WHY: unknown -- this rule exists in the code but nobody knows why" for a business logic decision, that's not a failure of the process. That's the process working. You found a rule that's been running in production with no justification. Now someone can decide whether it stays or goes.
When BackForging a business application, many WHY blocks aren't technical. They're business logic: "because the compliance department requires it," "because the vendor contract specifies 90-day retention," "because that's how this industry processes returns." This context doesn't exist in the code. It exists in meetings, contracts, regulatory requirements, and the client's institutional knowledge.
Extracting the technical "what" from code is straightforward. An AI agent can do it. Extracting the business "why" requires conversation with the people who made the business decisions. This is communication and domain expertise work, not engineering work. The person doing the BackForge needs access to the stakeholders who know why the business rules exist, not just the developers who implemented them.
This is where BackForging as a service becomes valuable. A freelancer or consultant who can sit with the client, ask the right business questions, and produce WHY blocks that capture business rationale is doing work that can't be offshored to someone who never met the client. The technical extraction is commoditized. The business context is not.
- Before a major refactor -- BackForge the affected domains so the refactor has a spec to work from
- Before a language/stack migration -- BackForge the whole project, swap conventions, rebuild
- When inheriting a codebase -- BackForge to understand what you've inherited and where the risks are
- When scaling a solo project to a team -- BackForge so new team members have a spec to read instead of reverse-engineering the code themselves
- When the original developers are gone -- the code is all you have; BackForging is how you extract the knowledge before it's needed under pressure