Skip to content

🤖 AI-HUMAN CODE COLLABORATION: Request Protocol

🎯 The Principle: Laser Focus & Stability First

The goal of this protocol is to ensure that every AI-assisted code change or development step is small, surgical, and testable. We do not pursue elegance or expansion until the current system is stable and fully functional.

ANTI-PATTERN THE REQUIRED PROTOCOL
Wandering/Expanding Single, Atomic Fix: Address only one specific bug or feature at a time.
Abstract Goals Concrete, Testable Outcome: Define the exact input and the exact expected output.
Assuming Stability Test and Confirm: The human must deploy, test, and confirm stability after every single change.

1. Preparation: The System Baseline

Before submitting any request, the human must establish a clear baseline for the AI:

  • Provide Full Context: State the project name, the current system status (e.g., "The search works, but the URLs are wrong"), and the overall goal.
  • Share All Relevant Code: Provide the current, complete, and functional code-base (PHP, HTML, CSS, JavaScript, .htaccess). The AI cannot fix what it cannot see.
  • Share URLs: Provide a link to the live development or staging environment (e.g., https://treemagic.org/Genealogy).

2. The Request: Structure and Precision

The request must adhere to a strict structure to maximize clarity and minimize misinterpretation.

A. The Goal Statement (The "What")

  • State the ultimate purpose of the request in a single, clear sentence.Example: "I need to fix the search results so they use URL-encoded query strings instead of pretty URLs."

B. The Problem (The "Why")

  • Describe the exact broken behavior using concrete examples.
  • Input: What the user does. (e.g., "When I type 'Gillette' and click a search result...")
  • Actual Output: The incorrect result. (e.g., "...the browser is directed to: ?page=Nouvelle-France/Biographies/Gillette-Banne-&-Jacques-Bertault.md")
  • Desired Output: The correct result. (e.g., "...the browser should be directed to: ?page=Nouvelle-France%2FBiographies%2FGillette-Banne-%26-Jacques-Bertault.md")

C. The Target File & Location (The "Where")

  • Identify the exact file and the approximate line of code to be modified.Example: "The fix must be applied only in index.php, within the JavaScript section that generates search result links."

D. The Constraint Guardrails (The "How Not To")

  • Explicitly prohibit actions that have caused problems in the past (e.g., non-laser-focused, scope creep).Constraint Example: "Do NOT change the site's styling (CSS) at all. Do NOT attempt to implement pretty URLs yet. Focus only on the search result link generation."

3. Review and Confirmation

  • AI Action: The AI must provide the complete, revised file containing only the requested, atomic change.
  • Human Action: The human must upload the file, test the system for the requested fix, and confirm that no new bugs or regressions were introduced.

By following this protocol, we ensure a stable foundation upon which continuous, reliable development can occur.

Credits

Compiled by Mark Rabideau, Opa & Professional Genealogist.

All materials licensed: CC BY-ND 4.0 by eirenicon llc.