siwes-logbook

name	siwes-logbook
description	Generate a SIWES / industrial-training log book from a student's real git history and pull requests. Use when a student (intern, IT/SIWES placement) wants to reconstruct what they did at their organisation, week by week or day by day, from commits and PRs across one or more repositories.

SIWES Log Book Builder

Reconstruct an accurate, defensible industrial-training log book from a student's own version-control history. What you produce feeds an official academic record (a hand-written book signed by a supervisor), so it must be truthful. Never invent work, dates, or deliverables, and never pad.

Core principle: two sources of truth

Use commits and pull requests together, not one instead of the other:

• Commits give the day-by-day narrative (what was touched each day, with real dates).
• PRs give the deliverables (clean, titled units of shipped work) and catch squash-merged work whose individual commits are hard to attribute.

Where one source doesn't exist (e.g. a personal repo with no PR workflow), say so and rely on the other — do not fabricate the missing one.

Prerequisites & assumptions

• This skill is written for GitHub with the gh CLI. Confirm gh is installed and authenticated (gh auth login) and that the student has access to the org/repos in question.
• For GitLab / Bitbucket / Azure DevOps / self-hosted git, or local-only repos with no remote, skip the gh/org-search steps and work from clones with git log (see fallback below). The structure, caveats, and integrity rules all still apply.
• Local git log fallback (any host)

Questions to ask before starting

Ask these up front (batch them). Don't guess where the answer changes the output:

1. Identity — What name / email / GitHub username are the commits under?
2. Scope of repos — Which org(s) and which repos? Are there personal repositories that are actually work projects? (These won't appear in an org-wide search — they must be named explicitly.)
3. Access method — GitHub via the gh CLI (works for remote, all repos, PRs), or local clones (git log)? Prefer gh for completeness; use local only when told to.
4. Start date — When did they join? If unknown, infer it from their first commit and confirm.
5. Log book structure — This drives the whole layout. Common formats:
   • Daily entries grouped by week (most SIWES books).
   • One summary paragraph per week.
   • Weekday-only grid (Mon–Fri). Ask which, and whether weekend commits should be folded into adjacent weekdays.
6. Open / unmerged PRs — Include in-review PRs as completed? (Often yes if they were opened recently and are expected to merge — mark them honestly.)
7. Exclusions — Test/sandbox/superseded PRs and throwaway repos should usually be left out. Confirm.
8. Output — Single markdown file? Per-project split? CSV/table for transcription?
9. Format & redaction — The official record is almost always a physical, hand-written book; the markdown is a private aid the student transcribes from. Default to producing two files: a full private copy for the student's own reference, and a redacted copy that is safe and easy to hand-copy into the physical book. Keep the redacted entries concise and legible (short daily lines) so transcription is quick. Never overwrite the full copy with the redacted one.

Process

1. Discover the full surface area — do not assume one repo

A student's work may be spread across several repositories.

• Read the remote of any local clone to find the org.
• Confirm gh auth status and the GitHub login.
• Find the commit email(s). Also check Co-authored-by: trailers, since paired work can be attributed to a single committer.
• Search the whole org for every repo they committed to, then paginate and bucket to get a per-repo count. Compare this total against what you've gathered — if it's higher, you're missing repos.
• List the student's personal repos separately and ask which are work projects.

2. Pull commits per repo

• Capture commit.author.date, the SHA, and the full message (not just the first line — bodies often contain the real engineering detail).
• Dedupe (squash/rebase can duplicate (date, message) pairs) and drop merge commits.

3. Pull pull requests

gh api -X GET search/issues -f q="org:<ORG> type:pr author:<USER>" --paginate

Record number, repo, state, merged-or-not, title, created date. For personal repos, query the repo directly (repo:<USER>/<REPO> type:pr) — they may have zero PRs, which is fine. Use commits directly then

4. Understand each project before describing it

Read each repo's top-level docs (e.g. README) so descriptions are accurate (what the service is, its stack) rather than guessed from commit messages.

5. Build the timeline

• Bucket commits + PRs by ISO week (Monday start), then by day within the week.
• Write each day as a concise, concrete sentence of what was done; attach the PR(s) the work delivered as that week's deliverables.
• Translate terse commit messages into readable prose, but keep the real technical specifics (the actual bug, the actual decision) — that's what reads as genuine engineering.

Critical caveats (state these in the output)

• Commit search indexes default branches only. Work on unmerged feature branches, or squash-merges committed under a colleague's name, may not appear. PRs help close this gap.
• Org search misses personal repos. They must be named by the student.
• Personal repos may have no PRs — commits are then the sole source; never invent PR numbers for them.
• The ticket system (Jira/Linear) is the authoritative record of assigned work and may capture tasks that never became a commit/PR. Commits+PRs are the code-side view only.
• A gap in commits is not always a holiday — it can mean a missed repo. Investigate before labelling it a break.
• Commit/PR search is rate-limited and caps at ~1000 results, and only matches commits whose author is linked to the GitHub account. Heavy contributors over a long placement may need per-repo pulls (Step 2) rather than search alone. Always reconcile counts (see Operational notes).

Confidentiality — redact, but keep the plot

SIWES / IT log books are typically physical, hand-written books, signed by an industry supervisor and submitted to the university. The markdown you produce is not submitted — it's a private tracking aid the student copies from, by hand, into the physical book. That means whatever lands in the redacted copy is what gets transcribed into the official record. So redaction has two failure modes, and you must avoid both:

• Leaking — material that must never leave the company ends up in the redacted copy and gets hand-copied into the submitted book.
• Over-redacting — abstracting so hard the entries become vague and generic, useless both as a personal memory aid and as evidence of real, skilled work. An assessor cannot grade "did some backend work; fixed some issues."

Redact by category, not by blanket vagueness. Decide per item:

Strip / generalise (sensitive)	Keep (generic — proves competence, leaks nothing)
Secrets, keys, tokens, connection strings (even partial)	Standard, widely-used technologies and methods, named generically (the language/framework, common auth standards, caching, database migrations, testing, CI)
Security-vulnerability detail — the flaw, its class, the affected component, the reproduction, the fix technique, any unpatched weakness	The neutral outcome only — e.g. "addressed findings from a security review and added tests"
Internal hostnames, URLs, IPs, cluster/namespace names, config-key names, internal class/file names, ticket IDs, infra-vendor names	The shape of the work: what was built and the general engineering approach
Internal project codenames and unreleased products/features	A neutral descriptive substitute (e.g. "an internal web service", "a public marketing page")
Customer / PII / financial data; confidential ticket content	Dates, weekly/daily structure, skills learned

Keep deliverables, drop the IDs. Keep plain-language descriptions of what shipped each week, plus any in-review items the student wants counted. Omit PR/commit numbers, ticket IDs, and internal links by default — they mean nothing when hand-copied into a physical book and only add transcription noise. An aggregate count (e.g. "around 40 pull requests over the period") is fine as a personal summary. Neutralise any deliverable description that names a flaw.

When a single item is genuinely ambiguous, ask the student rather than defaulting to maximum vagueness. The goal is to convey what they did and learned at a level a supervisor can recognise — not to reproduce internal specifics, and not to flatten real engineering into mush. If the employer has an NDA or disclosure policy, defer to it.

Integrity rules

• Never fabricate dates, work, PR/ticket numbers, or impact figures.
• Exclude test/sandbox PRs and superseded iterations from "deliverables" — listing them misrepresents real output.
• Mark in-review PRs honestly (e.g. a ‡ in review note) even if presenting them as done at the student's request.
• If the log relies heavily on terse commit messages for a project, say so — let the student add detail you can't verify.

Output template

# SIWES Log Book — Industrial Training Record
**Student:** … **Organisation:** … **Role:** … **Period:** …
[short note on method + caveats]

## Projects Touched
| Project | Stack | What it is |

## WEEK N — <date range>
*Project: …*
- **<Day DD Mon>** — <concise concrete description>.
- …
**Deliverables:** <plain-language description>, <description> ‡, …

## Summary
[duration, aggregate count, skills/technologies table]

(‡ marks an in-review item presented as a completed deliverable at the student's request. The redacted copy omits PR/commit numbers and IDs; the full private copy may keep them.)

Operational notes

• All gh api and git log commands here are read-only — they fetch history and don't modify anything. If network is unavailable the calls fail with connection errors; retry or run them where the host (e.g. api.github.com) is reachable.
• The GitHub commit-search endpoint needs the Accept: application/vnd.github.cloak-preview header.
• Reconcile your gathered total against the org-wide total_count as a completeness check before writing.