Applying SHAPR in AI-Assisted Research Software Development: Lessons Learnt from Building a Share Trading System
This paper presents a case study of applying the SHAPR framework to develop a modular share trading system, demonstrating how structured documentation, iterative cycles, and a specific tool configuration can maintain continuity, traceability, and methodological clarity in AI-assisted research software development.
Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer
Imagine you are a solo chef trying to invent a brand-new, complex recipe for a dish that has never existed before. You decide to use a super-smart, hyper-fast kitchen robot (Generative AI) to help you chop vegetables, mix spices, and even suggest new flavor combinations.
The robot is amazing. It works ten times faster than you. But here's the problem: because it's so fast, you might lose track of why you added a specific spice, or the robot might accidentally change the name of an ingredient halfway through, leaving you with a confusing mess of notes. You end up with a great-tasting dish, but you can't explain how you made it, or reproduce it later.
This paper is about a researcher named Ka Ching Chan who faced this exact problem while building a "Share Trading System" (a piece of software that simulates buying and selling stocks). To solve the chaos, he used a set of rules called SHAPR.
Here is a simple breakdown of what SHAPR is and what he learned, using everyday analogies.
What is SHAPR?
SHAPR stands for Solo, Human-centred, AI-assisted Practice.
Think of it as a safety harness for working with AI.
- Solo: You are the only human in the kitchen.
- Human-centred: You are the Head Chef. The AI is your sous-chef. The AI does the chopping, but you decide what the dish tastes like and whether it's safe to eat.
- AI-assisted: You use the robot's speed, but you don't let it drive the car.
The Big Problem: The "Black Hole" of AI
When you work with AI, it's easy to have a great conversation, get some code, and then forget where you were five minutes later. The AI might suggest a variable name like data_1, and then later suggest data_2, and suddenly your code is a tangled knot of confusion. This is called "drift."
In research, if you can't explain how you got your results, the results don't count. You need a paper trail.
The Solution: The "Three-Room" Kitchen
The researcher didn't just use one tool. He set up a "linked workspace" with three distinct rooms, each with a specific job. This kept the chaos organized:
- The Chat Room (ChatGPT): This is where you talk to the robot. It's for brainstorming, asking "What if we try this?", and getting quick code snippets. It's messy and fast.
- The Workshop (PyCharm): This is where the actual building happens. This is where the code lives and gets tested.
- The Ledger (Obsidian): This is the most important room. It's your "Source of Truth." It's a digital notebook where you write down the decisions you made in the Chat Room and the rules for the Workshop.
The Magic Trick: You don't write the Ledger after you finish. You write it while you work.
The Five Golden Lessons (The "Secret Sauce")
The paper found five key things that made this system work. Here they are, translated into metaphors:
1. The "Contract" Stabilizes the Robot
The Lesson: Before you ask the AI to build something, you must write a "contract."
The Analogy: Imagine hiring a contractor to build a deck. If you just say, "Build me a deck," they might build a wooden one, then a metal one, then a glass one. You need a contract that says: "It must be 10x10 feet, made of cedar, with 4 railings."
In the paper: The researcher wrote "contracts" (rules) for the code before the AI started coding. This stopped the AI from changing its mind or using confusing names.
2. The "Source of Truth" Keeps Everyone on the Same Page
The Lesson: You need one single place that holds the current "truth" of the project.
The Analogy: Imagine a group project where everyone has their own notebook. One person writes "Meeting at 5 PM," another writes "Meeting at 6 PM," and a third writes "Meeting at the park." Chaos! You need one master calendar that everyone updates.
In the paper: The researcher kept a "Source of Truth" document in his Ledger (Obsidian). If the AI changed something, he updated this document immediately. This ensured that the code and the notes always matched.
3. The "Snapshot" Saves the Game
The Lesson: When you finish a stage of work, take a "snapshot" before moving to the next.
The Analogy: Think of a video game. You don't play for 10 hours without saving. If the game crashes, you lose everything. You need to hit "Save" at the end of every level.
In the paper: At the end of every "Development Cycle" (like a level in a game), the researcher took a snapshot of the code and the notes. This meant if he got lost later, he could jump back to the last "Save Point" and start fresh without panic.
4. The "Quick Capture" vs. The "Polished Note"
The Lesson: Don't try to write perfect notes while you are coding. Just grab the thought, then clean it up later.
The Analogy: Imagine you are hiking and see a beautiful bird. You don't stop to paint a masterpiece; you just take a quick, blurry photo with your phone (Quick Capture). Later, when you are sitting in a café, you use AI to help you write a beautiful description based on that photo.
In the paper: The researcher used "Quick Captures" to jot down ideas instantly while coding. Later, he used the AI to turn those messy notes into clean, organized documentation. This kept him focused on coding without getting bogged down in paperwork.
5. Setting Up the Kitchen Is the Work
The Lesson: Spending time setting up your tools and rules isn't a waste of time; it's part of the research.
The Analogy: Before you bake a cake, you have to preheat the oven and measure your flour. That isn't "cooking" yet, but if you skip it, the cake will burn.
In the paper: The time spent setting up the Chat Room, the Workshop, and the Ledger actually helped the researcher understand the problem better. The setup was the learning process.
The Takeaway
This paper tells us that using AI for research isn't just about typing "Write me code." It's about discipline.
If you let the AI run wild, you get a fast but messy result that you can't trust. But if you act as the Head Chef, using Contracts, keeping a Master Ledger, taking Snapshots, and using Quick Captures, you get the speed of AI with the clarity and reliability of human research.
The result? A share trading system that works, but more importantly, a clear, honest story of exactly how it was built.
Drowning in papers in your field?
Get daily digests of the most novel papers matching your research keywords — with technical summaries, in your language.