Engineering Weekly Report

intent

produce a weekly engineering status report that teams send to stakeholders, managers, and themselves. the format is fixed week-over-week so readers know exactly where to look: shipping progress at the top, decisions in the middle, risks and next steps at the bottom. the report must be readable in under 2 minutes. use this skill when asked to write a team update, weekly engineering report, sprint status email, or standing team communication. avoid prose walls: use bullet points, status tags, and short tables. if metrics are not provided, leave the metrics section with [data needed] markers rather than fabricating numbers.

inputs

required information to gather:

• team name and report period (team name plus week number or date range, e.g., "Platform Team, Week 21, May 12, 16")
• work items shipped this week (what was completed and released or merged)
• work items in progress (what is actively being worked on, with rough percent-complete if known)
• blocked items (what is blocked, who owns the block, and what is needed to unblock)
• key decisions made (any architecture, process, or priority decisions made this week)
• decisions needed next week (any decisions that need to be made soon and who needs to make them)
• risks and escalations (anything that threatens next week's commitments or needs leadership visibility)
• next week's top priorities (the 3 to 5 things the team plans to accomplish next week)

optional inputs:

• key metrics: reliability (error rate, p99 latency), velocity (story points completed), or other health indicators
• team health notes: PTO, new joins, attrition, morale signals worth noting
• sprint or iteration number (if the team runs sprints)
• prior week metrics (for trend calculation)
• on-call owner for this week and next week

external connections:

• none required (this is a document generation skill, not an integration)

context assumptions:

• user can provide or retrieve the above information from jira, linear, datadog, honeycomb, or similar tools
• user has authority to share this information with intended distribution list
• team operates on a weekly reporting cadence

procedure

1. collect report metadata

   • input: team name, report period (week number and date range), author name, distribution list
   • output: header section with team name, week number, date range, author, and distribution

2. gather shipping progress data

   • input: list of work items shipped this week (features, fixes, infra changes) with one-line descriptions and impact
   • output: "Shipped This Week" table with columns: item, description, impact. if no items shipped, write "no items shipped this week." (this is rare but possible)
   • input: list of work items in progress with owner, percent-complete or status, and target ship date
   • output: "In Progress" table with columns: item, owner, status (e.g., "~40% / On Track / At Risk"), target ship date. if nothing in progress, write "no active work items." (this signals a problem and should be escalated)
   • input: list of blocked items with owner, blocker description, date blocked, and specific unblocking action needed
   • output: "Blocked" table with columns: item, blocked since, blocker description, owner, needed to unblock. if no blocks, write "no active blockers." do not accept vague blockers like "waiting on X" (go back to the owner and ask "what specifically is needed to unblock this?")

3. compile metrics section

   • input: key metrics from this week and last week (error rate, p99 latency, deployment frequency, story points, on-call page volume, or other team-specific metrics)
   • output: metrics table with columns: metric, this week, last week, trend (up/down/flat arrow), target. include one line of context for any metric that moved materially week-over-week (e.g., "Error rate spike on Tuesday tied to downstream dependency outage, resolved by EOD.")
   • decision: if metrics are not provided, replace table rows with "[data needed: provide metric values for this section]" (do not fabricate numbers)

4. record decisions

   • input: list of decisions made this week with rationale, owner, and whether stakeholders were informed
   • output: "Made This Week" table with columns: decision, rationale (one sentence), owner, stakeholders informed (yes/no and list). if no decisions made, write "no major decisions this week."
   • input: list of decisions needed next week with context, deadline, and decision owner
   • output: "Needed Next Week" table with columns: decision, context (why it matters), deadline, decision owner (name or role, not "TBD"). if no decisions pending, write "no decisions pending."

5. surface risks and escalations

   • input: list of risks with likelihood (high/med/low), impact (high/med/low), mitigation, and escalation path
   • output: "Risks and Escalations" table with columns: risk, likelihood, impact, mitigation, escalate to. add a separate line: "escalations this week: [any item needing immediate leadership attention, called out explicitly]" or "none." do not bury escalations inside a table row
   • decision: if a risk has both high likelihood and high impact, explicitly name the escalation path and owner. if no escalations, write "none."

6. capture team health

   • input: team capacity this week, PTO/out-of-office names and dates, new joins/departures, on-call owner this week and next week
   • output: "Team Health" table with columns: item, status. add a "team notes" line for morale, workload, or team dynamic signals (keep this factual and constructive). if nothing to note, omit the team notes line

7. define next week's priorities

   • input: list of 3 to 5 priorities for next week, each with owner and definition of done
   • output: numbered list (1-5) formatted as "[priority name] - [one sentence: what done looks like and who owns it]". priorities must be outcomes, not activities (e.g., "ship auth redesign" not "work on auth redesign")
   • input: any capacity risks next week (PTO, incident remediation, etc.)
   • output: "capacity risk" line below the priorities list if applicable, or omit if no risks

8. add appendix (conditional)

   • input: sprint number, committed story points, completed story points, carried-over points
   • output: "Sprint Scorecard" table with columns: sprint, committed, completed, completion rate, carried over. include prior sprint and current sprint (at midpoint). only add this section if the team runs sprints

9. assemble final report

   • input: all sections from steps 1-8
   • output: complete report formatted as markdown with clear section headers, tables, and visual breaks. add footer with "questions or corrections: [slack channel or email] | next report: [date]"
   • editorial check: ensure report fits on one printed page and is readable in under 2 minutes. if longer, trim lowest-value sections (usually the sprint scorecard appendix or verbose team notes)

decision points

if metrics are not available:

• do not estimate or fabricate numbers. mark the field as "[data needed: provide metric values]" instead. stakeholders making decisions on invented data is actively harmful.

if no items were shipped this week:

• write "no items shipped this week." this is a signal that the team may be blocked, under-resourced, or misaligned on priorities. escalate if this pattern repeats.

if no work is in progress:

• write "no active work items." this is unusual and should trigger a conversation with the team lead about capacity, priorities, or blockers.

if a blocked item lacks a specific owner or unblocking action:

• go back to the reporter and ask "who owns this? what is the concrete next step to unblock it?" do not accept vague entries like "waiting on platform team."

if a decision is pending but has no named owner:

• assign a decision owner before the report ships. "TBD" is not a valid entry and signals the team has not yet committed to the decision.

if an escalation is flagged but has no escalation path:

• explicitly name the leader, team, or channel to which the escalation is being sent. do not bury it in a table row.

if a priority is written as an activity instead of an outcome:

• rewrite it. "work on auth redesign" becomes "complete auth redesign and deploy to staging by Friday." outcomes allow stakeholders to evaluate whether the team delivered.

if the report exceeds two printed pages:

• trim the lowest-value sections in this order: team notes (if generic), sprint scorecard appendix, verbose metric context, lowest-priority next-week items (keep top 3). length signals the author has not done the editorial work of deciding what matters to stakeholders.

if team capacity next week is reduced (PTO, incident response, etc.):

• add a "capacity risk" line under the priorities section so stakeholders can calibrate expectations.

output contract

format: markdown document with the following sections in order:

1. header: team name, week number, date range, author, distribution list
2. shipping progress: shipped this week (table), in progress (table), blocked (table)
3. key metrics: metrics table with this week, last week, trend, target; or "[data needed]" markers if unavailable
4. decisions: made this week (table), needed next week (table)
5. risks and escalations: risks table, plus explicit escalations line
6. team health: capacity, PTO, new joins, on-call, team notes (optional)
7. next week's priorities: 3 to 5 numbered outcomes with owners and definition of done; capacity risk line (optional)
8. appendix (if applicable): sprint scorecard table
9. footer: contact info (slack or email), next report date

file location: typically saved as markdown (.md) file in a shared drive, wiki, or email. filename convention: engineering-report-[team-slug]-[week-number].md (e.g., engineering-report-platform-team-week-21.md)

data format: all tables use markdown syntax with pipe delimiters. all trends use arrow indicators (↑ / ↓ / →). all blockers name a specific owner and unblocking action. all decisions name an owner. all priorities are outcomes, not activities.

completeness criteria:

• every blocked item has a named owner and a specific unblocking action
• every pending decision has a deadline and a named decision owner
• every priority is written as an outcome, not an activity
• escalations that need leadership attention are called out explicitly in a separate line, not buried in a table
• metrics are either real data or marked "[data needed]" (no fabricated numbers)
• report is scannable in under 2 minutes and fits on one printed page

outcome signal

the user knows the skill worked when:

• the report is distributed to stakeholders (via email, slack, wiki, or shared drive) and no one asks "what does this metric mean?" or "who is blocking this?" because the data is clear and actionable
• team leads can point to the next-week priorities and say "yes, that is what we are doing" without clarification
• escalations are surfaced early enough that leadership can act on them (not discovered in a post-mortem)
• the report becomes a reference document within the team and across leadership; people cite it in decisions and standups
• trends in metrics, blockers, and capacity become visible week-to-week; patterns (repeated blockers, declining velocity, PTO clusters) are caught early
• the report is consistently under 2 minutes to read, and stakeholders do not skip it or ask for "just the summary"
• if a decision was pending, the report from next week confirms it was made (or escalated) and the team moved forward