.png){kind=small}
Workspace Checkpoint: Reverse-Engineer a Module
Pick a real module, produce an architecture write-up.
What You Will Learn
- Apply workspace skills end-to-end.
- Reverse-engineer a module's architecture.
- Verify explanations against code.
- Produce a 2-page write-up.
- Document for team knowledge transfer.
Why This Matters
Reverse engineering cements workspace skills. The write-up becomes team documentation. The process builds the verification habit that pays off forever.
Concept Explained
Pick a module you don't fully understand. Use workspace skills (IN-09 to IN-15) to reverse-engineer its architecture. Produce a 2-page write-up with diagram.
How It Works
Use @workspace for architecture overview. Scope to specific files for depth. Trace data flow. Generate diagram. Verify each claim against code. Write up.
Step-by-Step Tutorial
1. Pick a module
Choose one you don't fully understand — ideally one with tribal knowledge.2. Architecture overview
@workspace: 'What does this module do? List main files and responsibilities.'3. Deep dive per file
Attach each file. Ask: 'What does this file do? Main functions? Dependencies?'4. Trace data flow
'How does a [request/event] flow through this module? List each file and function.'5. Generate diagram
Ask for Mermaid or SVG architecture diagram.6. Verify
Read actual code. Note any discrepancies.7. Write up
2-page summary: purpose, architecture, data flow, gotchas.Real-World Example
A new team member reverse-engineered a legacy billing module. Produced a 2-page write-up that became the team's canonical reference. Caught 2 hallucinations during verification. The write-up saved the next 3 hires ~6 hours of onboarding each.
Example Prompts / Commands / Code
# Module: Billing
## Purpose
Processes monthly invoices, handles payments, manages subscription state.
## Architecture
- billing/controller.ts — HTTP endpoints
- billing/service.ts — Business logic
- billing/repository.ts — Database access
- billing/types.ts — Type definitions
- billing/events.ts — Event publishing
## Data Flow
1. POST /billing/charge → controller.charge()
2. controller calls service.processPayment()
3. service calls repository.getUserSubscription()
4. service calls payment gateway
5. service publishes event via events.publishChargeSucceeded()
6. repository.updateSubscriptionStatus()
## Gotchas
- Payment gateway has 30s timeout; service doesn't (see issue #142)
- Event publishing is async; failures are logged but not retried
- Subscription state is cached in Redis for 5 min
## Diagram
[Mermaid or SVG here]
Common Mistakes
- Picking a module you already understand — defeats the exercise.
- Not verifying against code — hallucinations slip into the write-up.
- Skipping the diagram — visual is essential for retention.
- Not writing up — the deliverable is the doc, not the conversation.
Best Practices
- Pick a module with tribal knowledge — high value to document.
- Use layered prompts: architecture → files → data flow.
- Generate a diagram.
- Verify every claim against code.
- Write up as 2-page summary for team knowledge transfer.
Troubleshooting
| Problem | How to Fix |
|---|---|
| Can't understand the module | Start smaller — pick a single file, then expand. |
| Write-up is too long | Aim for 2 pages. Detail goes in code comments, not the write-up. |
Practical Exercise
Your Turn
This IS the exercise. Pick a module, reverse-engineer it, produce a 2-page write-up with diagram. Save in your team's wiki.
Professional Challenge
Present your write-up at a team meeting. Get feedback. Iterate. The write-up becomes canonical documentation.
Key Takeaways
- Reverse engineering cements workspace skills.
- Pick a module with tribal knowledge.
- Use layered prompts: architecture → files → data flow.
- Generate a diagram.
- Verify against code; write up as team doc.
Frequently Asked Questions
Should I commit the write-up to the repo?
What if my write-up disagrees with a teammate's understanding?
Further Reading
Official References
SEO Metadata
SEO title: Workspace Checkpoint: Reverse-Engineer a Module
Meta description: Pick a real module, produce an architecture write-up.
Primary keyword: workspace checkpoint
Secondary keywords: workspace checkpoint: reverse-engineer a module
Search intent: Informational
URL slug: /workspace-checkpoint-reverse-engineer-module
Categories: AI Tools, GitHub Copilot
Tags: GitHub Copilot, Intermediate, Checkpoint, Reverse Engineering, @workspace, IMCSEIAN, Tutorial, IMCSEIAN
Featured image concept: IMCSEIAN lesson card for Workspace Checkpoint: Reverse-Engineer a Module
Comments
Comments
Post a Comment