docs: #4 workflow guide and AI decision log #33
Merged
+185
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
docs/WORKFLOW.md — branching, conventional commits, PR size and review expectations. Records the two corrections the group made to the process: implement each issue from its requirements rather than splitting the archived prototype, and drop the formal pre-coding plan comment in favour of clear issues plus PR descriptions that say what was done and tested. docs/AI-USAGE.md — rewritten as a decision log, one entry per PR: what we asked for, what we took, what we changed or rejected and why, and what the reviewer pushed back on. Opens with an honest account of the scaffold prototype and why it was closed unmerged, including the three bugs the smoke suite caught that the unit tests had missed. README.md — project intro, getting started, milestone table, and links to both documents. Co-Authored-By: opencode <noreply@opencode.ai>
House style is plain hyphens. No functional change. Co-Authored-By: opencode <noreply@opencode.ai>
erikhfj
force-pushed
the
docs/4-workflow-and-ai-log
branch
from
cce3f1a to
168d2df
Compare
Robert's position on process is that clear issues plus small PRs with a
good description of what was done and tested is what matters. The
original wording turned that into a gate ("LGTM is not a review, ask a
question"), which is the same species of overhead as the plan-before-code
step we already dropped.
Reworded so the intent survives and the mandate does not. Trivial changes
may simply be approved.
Co-Authored-By: opencode <noreply@opencode.ai>
Replaced the prose decision log with a four column table: Date, Who, Tool, Used for. The narrative entries were long enough that nobody was going to read them, and the course requirement is documentation of how the tools were used. What survives in the table is what was actually used for, including the bugs the smoke tests and the code review caught. Two rows have a dash in the Tool column on purpose. Rachel overruled the plan to split the generated code into smaller PRs, and Robert overruled the plan-before-code step. Those are the rows that show our own control rather than just tool usage, so they belong in the same table rather than in a separate note. Left empty rows for robertky, evenkkl and rachelks to fill in. Updated WORKFLOW.md to describe the table instead of the old format. Co-Authored-By: opencode <noreply@opencode.ai>
Provided documentation on AI usage for Even
Sign in
to join this conversation on GitHub.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What this does
Documentation for #4 - how we work in this repo, and an AI usage log that documents our own control over the process rather than just which tools were used.
Written from what the group actually agreed this week, including the two corrections to my first proposal.
What was done
docs/WORKFLOW.md- branch naming, conventional commits, PR size and review expectations.Two things in here come directly from your feedback and are worth flagging:
archive/scaffold-prototypeis a reference to check against or consult when stuck - not a source to paste from. Splitting the generated code into smaller PRs would only have fixed the git cosmetics.docs/AI-USAGE.md- rewritten as a decision log, one entry per PR: what we asked for, what we took, what we changed or rejected and why, and what the reviewer pushed back on. The format includes a "can defend line by line" field - if the author cannot explain a piece of the diff in a viva, it should not be in the PR.It opens with an honest account of the scaffold prototype: what it was for (answering two real design risks early), why it was closed unmerged, and the three bugs the smoke suite caught that the unit tests had missed. Recording it rather than quietly deleting the branch is the point.
README.md- project intro, getting started, the milestone table, and links to both documents. Keeps the course's merge rules intact.What was tested
Markdown only, so the relevant gate is formatting:
pnpm lint/typecheck/testdo not apply to this branch - it adds no code. It is branched frommainrather than from #1 so the two PRs stay independent.Notes
docs/AI-USAGE.mdhas a placeholderCan defend line by linefield in the template. I left it explicit rather than implicit because it is the one line that separates a log from a list of credits.Closes
Closes #4.