Skip to content

A3: Structural and Creational Patterns

A3 is a design review. You receive a codebase, a proposal to change it (an RFC), and a review of that proposal written by an AI agent. You return both documents with your comments in the margins, plus a short proposal of your own for the one decision you are most skeptical of. Nothing is implemented.

Submit on Gradescope by Sunday, September 20, 11:59 pm.

The Codebase

wtf is a terminal dashboard written in Go. It shows widgets (wtf calls them modules) such as clocks, a to-do list, and a git status pane, each configured in a YAML file.

Clone the course copy of the repository: https://github.com/CMU-17695/a3-wtf. It is wtf at a fixed commit (bb838c1). Do not update it to a newer upstream version.

You do not need to build or run wtf, and you do not need to know Go. Ask an AI agent to explain any line, any construct, or any language rule you meet (see AI Use below). The part that matters is how the application constructs its modules. You should begin by looking at app/widget_maker.go. The RFC tells you where its author looked. Where the consequences are is yours to find.

What You Receive

  • RFC-031 (PDF). A proposal to replace the function that constructs modules with a registry, a shared construction context, and one constructor signature for every module. Written by a teammate on the project. Its sections are numbered so that you can refer to them (e.g., 3.2).
  • An AI review of RFC-031 (PDF). Produced by running an AI coding agent on the course copy of the repository with the RFC as its input. It is reproduced exactly as the agent wrote it. It may be right, wrong, or shallow in places. Deciding which is part of the assignment.

Both PDFs are linked at the end of this page.

Deliverables

You will submit the following:

  1. RFC-031, returned with your comments in the margin, plus a class diagram of the module-construction code as it is today.
  2. The AI review, returned with your comments in the margin.
  3. A better approach for one decision in the RFC.

There is no separate reflection.

How comments work

A comment is a short note attached to one place in a document. Every comment you write, on either document, has three parts:

  • An anchor. The sentence, section number (such as 3.2), or diagram element it is about. In a PDF annotation, highlight the text or attach the note to it. On paper, draw a line to it.
  • A tag. One word at the start of the comment. On the RFC: blocking (the RFC cannot go ahead as written), question (the author has to answer before you can tell), or agree (the RFC is right here, and you can say why). On the AI review: agree (the review is right), disagree (the review is wrong or overreaches), or missing (something the review should have raised and did not).
  • A code pointer. At least one place in the course copy of wtf that supports the comment: a file and line number, or a file and function name. A comment that says the document contradicts itself may cite the other section in place of code. On the AI review, anchor by finding number or heading.

Below is an example from an unrelated, fictional codebase. Attach this note to the quoted sentence:

question: Section 2.1, “all exporters support cancellation”: export/csv.go, function Write, accepts no cancellation signal. How would callers cancel a CSV export under this proposal?

A comment with no anchor, or whose code pointer does not support it, does not earn credit. An agree earns credit only when it says what the document gets right and where the code shows it. Keep each comment under about 80 words. Depth is better than volume.

We grade comments for specific reasoning supported by the code and for coverage of distinct concerns. Extra comments do not automatically earn more credit. The RFC has more problems than any one reviewer will find, and the AI review has more claims than any one reader will check. We do not expect you to find everything. Six well-argued comments on the RFC and four on the AI review, each on a different concern, is a complete submission. A comment that finds a real problem earns the same credit whether the AI review found it too or not.

1. Your review of RFC-031 (40%)

Read the RFC against the code. Check the RFC’s claims against the code, and assess whether the code supports its proposed decisions. Write at least six comments.

Also attach a class diagram of the module-construction code as it is at bb838c1, before the RFC. Use the notation from the second studio session, selectively. Keep it to at most 10 of wtf's own types (third-party types such as tview.Pages do not count): the application, the construction function, the module interface, a shared base type, and one or two representative modules are enough. More than one type could count as the shared base. Name the one you chose and say in one line why. Show what constructs what and what holds what. Hand-drawn or digital is fine.

2. Your review of the AI review (30%)

Read the AI review against both the RFC and the code. Where it is right, say so and point at the code. Where it is wrong, overreaches, or repeats the RFC without checking it, say so and point at the code. Where it missed a concern you raised in deliverable 1, or one you find now, add a missing comment at the place in the review where that concern belonged, or at the end. Write at least four comments.

3. A better approach (30%)

Pick the one decision in the RFC that you are most skeptical of. Propose something better for that decision alone. Write at most 500 words plus one diagram, under these four headings, in this order:

  1. The decision. Which RFC decision you are replacing (section number), and what is wrong with it, with a code pointer.
  2. The proposal. What you propose instead. Put the diagram here: the changed part of the design, in the studio-2 notation, with what is new or changed distinguishable from what stays.
  3. What it makes cheaper later. A specific change that becomes easier, and where in the code the difference shows.
  4. What it costs. Every proposal costs something. A proposal with no stated cost is incomplete.

Keeping the current code for that decision, or a smaller change than the RFC's, is a legitimate answer when the argument is specific. No points depend on using a named pattern.

Questions That Might Help

Reviewers who are new to design review often do not know where to start. These questions work on any RFC. Ask each one of RFC-031 and write down where the answer takes you.

  1. What does adding one module touch today, and what does it touch under the proposal? List both.
  2. Which behavior that a user can see changes, and does the RFC say that it is changing?
  3. What state is shared across the whole program under the proposal, who writes it, and when?
  4. What does every module now receive that it did not need before, and what could it do with it?
  5. What does the proposal promise that the code, the language, or the build cannot deliver?
  6. What would a test have to do differently, and does the existing test still work?
  7. Does any argument the RFC uses against an alternative also apply to the proposal itself?

AI Use

An agent may tell you what the code does and what Go guarantees. Ask it anything about Go (what init() does, what a blank import is, who calls a function). Don't ask it what to think about the RFC or the AI review. (Reminder: You don't have AI helping out during the final exam.)

Work AI allowed?
Reading and navigating the codebase, and explaining Go Yes
Writing your comments No. Polishing the wording of a comment you wrote is fine.
The class diagram Explore the code with an agent as much as you like. Decide what goes in the diagram and draw it yourself, in any tool.
The better approach No. Polishing your wording is fine.

Every AI session is exported in full. See the transcript policy for formats and instructions.

Every comment identifies a passage or diagram element and cites supporting code. Both are checkable, and we check them. Submitting text you have not read will lose points on this assignment.

Submission

One zip file to the Gradescope assignment "A3", containing:

rfc-031-annotated.pdf
ai-review-annotated.pdf
as-is-diagram.pdf        (or .png / .jpg)
better-approach.pdf
transcripts/
  • Annotate the PDFs with any PDF tool (Preview, Acrobat, and most browsers can), or print them, write by hand, and scan. Handwriting must be legible.
  • transcripts/ holds one complete export per AI session. Screenshots and edited excerpts are not transcripts.
  • A few files, well under a megabyte. No packaging steps are needed.

A submission without transcripts is incomplete. The late policy applies.

Grading

We grade the specificity of your reasoning about this codebase. No points depend on agreeing or disagreeing with the RFC, on agreeing or disagreeing with the AI review, or on naming a pattern.

Component Weight Graded on
Review of RFC-031 40% Comments anchored and supported by the code. Specific reasoning and coverage of distinct concerns. The as-is class diagram.
Review of the AI review 30% Comments anchored and supported by the code. Specific reasoning and coverage of distinct concerns. Correct calls on where the review is right, wrong, or silent.
Better approach 30% One decision named with its problem. A proposal with a diagram. What it makes cheaper and what it costs, argued from the code.
Transcripts required Ungraded, but the submission is incomplete without them.

The Documents