Lesson 3 — Make the Case and Close the Loop

Module 5, Unit 4 | Lesson 3 of 3

By the end of this lesson, you will be able to:

Use your Commit Log Agent to draft a structured technical recommendation (S27)

Write a closing Commit Log entry that maps your work directly to KSB evidence (S25, B6)

Review and prepare your GitHub repository as a professional portfolio artefact (B6)

The recommendation drives a decision

There is a fundamental difference between a report and a technical recommendation. A report describes the situation. A recommendation resolves it — it tells someone what to do next and why, clearly enough that they can act on it without asking you to explain it further.

By this point in Module 5 you have built something real: an agent that makes API calls, invokes tools, validates input, recovers from failures, and logs its own operation. You have documented its architecture and catalogued its risks. What you have not yet done is synthesise all of that into a single argument — one that a senior stakeholder could read in ten minutes and understand exactly what you built, why, and what happens next.

That is what this lesson is for.

Build Part 1 — Let your agent draft the recommendation

Your Commit Log Agent can be used for this task. You built it to process structured prompts and return useful output — this is a structured prompt task. Add a recommendation_drafter.py module that uses your agent to draft each section of the technical recommendation:

# commit_log_agent/recommendation_drafter.py

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))


SECTION_PROMPTS = {
    "executive_summary": """
You are helping a software apprentice write a technical recommendation for their workplace AI project.

Based on the following architecture notes, write a one-paragraph executive summary (4 sentences maximum):
- What is recommended, in one sentence
- Why, in two sentences
- The main trade-off to be aware of, in one sentence

Architecture notes:
{architecture_notes}
""",

    "context_and_constraints": """
Based on the following project notes, write the Context and Constraints section of a technical recommendation.
This section should explain: what the system needs to do, what constraints shaped the decisions (data sensitivity,
team capability, budget, timeline), and what would have been different without those constraints.
Keep it to 2-3 short paragraphs.

Project notes:
{project_notes}
""",

    "recommendation": """
Based on the following architecture decisions, write the Recommendation section of a technical report.
State clearly: the chosen architecture, the platform(s) selected, the key components and why each was
chosen over the alternative. Be specific — name actual technologies, not just categories.
Every claim must be traceable to a decision that has already been made.

Architecture decisions:
{architecture_decisions}
""",

    "risks_and_mitigations": """
Based on the following risk register, write the Risks and Mitigations section of a technical recommendation.
Cover the three most significant risks. For each: name the risk, explain its potential impact,
and describe the specific mitigation already in place. Be concrete.

Risk register:
{risk_register}
""",

    "next_steps": """
Based on the following project status, write the What Happens Next section of a technical recommendation.
This section must contain specific, actionable steps — not vague intentions.
Each step should include: what needs to happen, who owns it, and what it unblocks.
A reader who has never seen this project before should know exactly what to do next.

Project status:
{project_status}
""",
}


def draft_section(section_name: str, context: str) -> str:
    """
    Drafts one section of the technical recommendation using the LLM.
    section_name must be a key in SECTION_PROMPTS.
    context is the text you provide as input for that section.
    """
    if section_name not in SECTION_PROMPTS:
        raise ValueError(f"Unknown section: {section_name}. Choose from: {list(SECTION_PROMPTS.keys())}")

    # Build the prompt by substituting whichever placeholder this section uses
    prompt_template = SECTION_PROMPTS[section_name]
    # Each template has exactly one placeholder — find and fill it
    for placeholder in [
        "{architecture_notes}", "{project_notes}", "{architecture_decisions}",
        "{risk_register}", "{project_status}"
    ]:
        if placeholder in prompt_template:
            prompt = prompt_template.replace(placeholder, context)
            break
    else:
        prompt = prompt_template + f"\n\nContext:\n{context}"

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You write clear, specific, professional technical documentation. "
                                           "You never use vague language. You always name specific technologies "
                                           "and concrete next steps."},
            {"role": "user", "content": prompt},
        ],
        max_tokens=500,
        temperature=0.3,
    )
    return response.choices[0].message.content.strip()


def draft_full_recommendation(
    architecture_notes: str,
    project_notes: str,
    architecture_decisions: str,
    risk_register: str,
    project_status: str,
) -> dict:
    """
    Drafts all five sections of the technical recommendation.
    Returns a dict keyed by section name.
    """
    inputs = {
        "executive_summary": architecture_notes,
        "context_and_constraints": project_notes,
        "recommendation": architecture_decisions,
        "risks_and_mitigations": risk_register,
        "next_steps": project_status,
    }
    drafts = {}
    for section, context in inputs.items():
        print(f"Drafting: {section}...")
        drafts[section] = draft_section(section, context)
    return drafts


if __name__ == "__main__":
    drafts = draft_full_recommendation(
        architecture_notes="Paste your ADD sections 1–4 here as a string",
        project_notes="Paste context about your workplace project here",
        architecture_decisions="List the key decisions from your ADD Section 4",
        risk_register="Paste or summarise your RISK_REGISTER.md rows here",
        project_status="Describe what is done and what remains open",
    )
    for section, text in drafts.items():
        print(f"\n{'='*60}\n{section.upper()}\n{'='*60}\n{text}")

Run it directly from the terminal: python -m commit_log_agent.recommendation_drafter. Fill in the five string arguments with content from your ADD, risk register, and current project status. The output is a first draft — not a finished document. Your job is to review every sentence, replace anything generic with something specific to your project, and add anything the model missed because it does not know your organisation.

The diagram below shows how your existing project evidence feeds each of the five recommendation sections, and where the model's draft output ends and your editing begins.

Coach Cora
The "What Happens Next" section is what separates a recommendation from a report. If a stakeholder reads yours and still does not know what to do, you have written a report. Each next step must name: the action, the person or team who owns it, and what it unblocks. Vague steps — "explore options", "continue investigation", "discuss with team" — are not steps. They are placeholders for thinking you have not yet done.

Build Part 2 — The recommendation document

Create TECHNICAL_RECOMMENDATION.md in the root of your repository. Use your drafted sections as a starting point and edit them into a final document. The five-section structure:

Section 1 — Executive Summary One paragraph. What you recommend, in one sentence. Why, in two sentences. The main trade-off, in one sentence. If a busy person reads only this section, they should know what you built and what you recommend.

Section 2 — Context and Constraints What the system needs to do. What shaped your decisions (data sensitivity, team capability, budget, timeline). What would have been different without those constraints.

Section 3 — Recommendation Your chosen architecture. The platform(s) you selected. The key components and why each was chosen over the alternative. Be specific — every claim here should trace back to a decision in your ADD.

Section 4 — Risks and Mitigations The three most significant risks from your risk register. For each: name it, describe its potential impact, and describe the specific control you have implemented. Not "we will monitor this" — name the code or configuration that addresses it.

Section 5 — What Happens Next The concrete steps required to move from this recommendation to implementation. At least three steps. Each step must have: an action, an owner, and what it unblocks.

Curious Cat

Amazon famously requires every new internal initiative to begin with a press release written as if the project has already succeeded — clear, specific, written for an outsider, with no jargon. The idea is that if you cannot write it, you do not yet understand it well enough to build it. The technical recommendation you are writing serves a similar purpose: it forces you to synthesise everything you have learned about your architecture into a form clear enough for someone else to act on. The quality of the writing is a reliable signal of the quality of the thinking.

Closing your Module 5 Commit Log

The final entry in your Commit Log is not a formality. It is the moment where you connect what you built to what you learned, and where your KSB evidence becomes explicit rather than implied.

Your closing entry must include:

What I built — One paragraph. The architecture pattern, the platform, the tools implemented, the defensive patterns added. Written for someone who has not been following your progress.

Key decisions — The three most important decisions you made. For each one, say whether — with the benefit of hindsight — you would make the same choice again and why.

KSB evidence — Complete the table below. Every row. If you cannot fill in a row, do not leave it blank — note what you would have done differently to generate the evidence.

KSB	How I demonstrated this in Module 5	Evidence (link or file)
K8
K9
K25
S25
S27
B6

What I would do differently — One thing you would change if you were starting Module 5 again. Be specific. "I would have structured my code better" is not an answer. "I would have built the tracer in L3.1 rather than L4.1 so my Unit 3 commits would have trace evidence attached" is an answer.

What I am taking into Module 6 — One open question, one skill to develop further, or one unresolved architectural issue that the next module will address.

Preparing your GitHub repository

Before you close this module, read through your repository as if you were a potential employer encountering it for the first time. Check:

README — Does it accurately describe what the repository contains? Does it mention the agent's capabilities, how to set it up, and what the key files do?
Commit history — Does it tell a legible story? Commits like "fix", "update", "misc" tell you nothing. Your commit messages should describe what changed and why.
File organisation — Are your modules cleanly separated? Is there any dead code, unused test files, or leftover experimentation that should be removed or moved to a branch?
Documentation — Are ADD.md, RISK_REGISTER.md, and TECHNICAL_RECOMMENDATION.md all committed and linked from the README?
Secrets — Run git log --all --full-diff -p -- .env to confirm no API keys appear anywhere in your commit history. This checks every commit across all branches (--all) for changes to .env files, showing the full diff (-p --full-diff). If the output is empty, no secrets were committed. If you see a line starting with +OPENAI_API_KEY=sk-... in the output, a key was committed at some point — even if deleted later, it remains in history and must be revoked immediately in your OpenAI dashboard.

This repository is a professional artefact. It represents not only what you can build, but how you think and how you work.

Build — Final commit

Commit the following to GitHub:

TECHNICAL_RECOMMENDATION.md — completed and edited (not the raw agent output)
Updated ADD.md — all six sections complete
Updated README.md — accurate and professional
Your final Commit Log entry

Add to your Commit Log: links to all three documents (ADD, Risk Register, Technical Recommendation), and your honest answer to "what would I do differently if I started Module 5 again?"

Checklist

recommendation_drafter.py runs and produces a first draft for each section
TECHNICAL_RECOMMENDATION.md is complete, edited, and specific — not the raw model output
My closing Commit Log entry includes the KSB evidence table with every row completed
My GitHub repository is in good shape: README accurate, commits legible, no secrets in history
All documents are committed and linked in my Commit Log

Quick Check

KSB evidence focus

S27 — Apply technical understanding to help align business needs with technical capabilities, supporting the development of solutions that are scalable, efficient, and aligned with the organisation's strategic objectives. Your completed ADD and Technical Recommendation are the primary S27 evidence for the entire module. The quality of your decision rationale — not the length of the documents — is the evidence.
S25 — Keep up to date with existing, evolving, emerging technologies and sector trends in AI, automation and technology including methods to evaluate vendor and supplier solutions. Your Platform Evaluation Matrix from Unit 2 and your ADD together demonstrate S25: structured, evidence-based evaluation of current AI solutions under real organisational constraints.
B6 — Shows curiosity and initiative, experimenting with AI and automation, while ensuring such exploration is conducted safely, ethically, and with regard for potential impacts. Your GitHub repository — built, documented and maintained throughout this module — is the most concrete B6 evidence you can produce. It shows initiative, iterative development, and professional habit-building across every commit.

Well done. You have designed, built, hardened, documented and justified an AI architecture. Your agent is not a prototype — it has validation, retry logic, fallback handling, a cost guard, a usage logger, and a documented risk register. In Module 6, you will take this foundation further.

Before you move on: your ADD is committed, your Commit Log is closed, and your GitHub repository tells the story of what you built and how you think. Those are the foundations Module 6 builds on.

Next: Module Survey