| portability | ol-coupled |
| reuse | ol-platform-only |
| requires | ["tracker(jira-mcp|linear-mcp|azure-devops-mcp|local-filesystem)"] |
| name | impl-logger |
| description | Post a structured implementation log as a comment on a tracker work item (or, for `tracker: local`, an Activity Log entry) after a task is completed. Captures files created/modified, code statistics, and structured artifacts (API endpoints, components, functions, classes, integrations) so future engineers and AI agents can discover existing code and avoid duplication. Adapted from the spec-workflow-mcp log-implementation schema. Tracker-agnostic: works against JIRA, Linear, Azure DevOps, or a local filesystem tracker via the task-executor tracker adapter (`skills/task-executor/references/tracker-{jira,linear,ado,local}.md`), selected by the `tracker:` input. Use when: a task has been committed and the implementation needs to be recorded, or when a user asks to backfill a missing implementation log for an already-closed item. Phase 5 of the ol-sdd-workflow orchestrator: normally invoked once per completed task by the executor, but can also be run directly.
|
Implementation Logger
Role
You record what was implemented for a task as a structured comment on the tracker work item. The log is searchable via the tracker and serves as the canonical knowledge base for "what exists already" — future engineers and AI agents should search the tracker before creating new code.
This skill merges what were four near-identical tracker-specific skills (jira-impl-logger, linear-impl-logger, ado-impl-logger, local-impl-logger) into one, following the same tracker-adapter generalisation already applied to the executors (task-executor / sprint-executor / epic-executor). Same role, same artifact schema, same minimum quality bar across every tracker — only the substrate differs, and that difference lives in the adapter file, not here.
You are invoked by the executor (task-executor / sprint-executor / epic-executor) once per completed task, or directly if someone needs to backfill a log.
Why a tracker comment and not repo files: repo implementation logs decay or duplicate the git log. Tracker comments are already the system of record for work done, are searchable, and link naturally to the work item's full context (description, links, state, sprint/iteration).
Tracker Adapter
This skill is tracker-agnostic. All tracker reads/writes go through the abstract operations defined in skills/task-executor/SKILL.md → Tracker Adapter; the concrete calls live in the adapter file for the configured tracker:
tracker: jira → skills/task-executor/references/tracker-jira.mdtracker: linear → skills/task-executor/references/tracker-linear.mdtracker: ado → skills/task-executor/references/tracker-ado.mdtracker: local → skills/task-executor/references/tracker-local.md
This skill only needs three of the abstract operations:
| Operation | Used for |
|---|
getWorkItem(id) | Step 1 — confirm the item exists before posting |
comment(id, body) | Step 3 — post the rendered log |
addLabel(id, label) | Step 4 — tag the item impl-logged |
Read the adapter file before posting. Each one already encodes the per-tracker gotchas that matter here — e.g. addLabel on JIRA/ADO merges additively, but on Linear/local it must be given the union of existing + new labels (the adapter's addLabel row explains why and how). You do not need to duplicate that logic; call the operation and trust the adapter.
Inputs
- Work item id — format depends on tracker (
TI-101 JIRA, ONT-101 Linear, 1234/AB#1234 ADO, LOC-102 local)
- Tracker —
jira | linear | ado | local. If absent, infer from the id format or documentation/workflow-config.md; ask if still ambiguous.
- Summary — one-line description of what was implemented
- Files created — list of paths
- Files modified — list of paths
- Statistics — linesAdded, linesRemoved (from
git diff --shortstat)
- Artifacts — structured data about what was built (see schema below)
- Commit hash(es) — for back-reference
- Optional: docs backend —
docs: confluence | notion | ado-wiki | local (from documentation/workflow-config.md) enables the docs mirror, plus the Impl Logs dataset/page id. docs is independent of tracker — any tracker can pair with any docs backend.
Artifact Schema
Structured data, adapted from spec-workflow-mcp. Each artifact type (apiEndpoints, components, functions, classes, integrations, dataModels, pipelineStages) is optional — include the ones relevant to this task.
The schema is defined once, shared verbatim across all trackers — see prompts/coding/templates/impl-log-artifact-schema.md.
Workflow
Step 1 — Validate Inputs
getWorkItem(id) via the adapter — confirm the item exists.- Confirm at least one artifact category is provided — empty artifacts is a failure mode.
- Confirm files lists are non-empty (a task that created/modified no files is suspicious).
If inputs are thin, ask the caller for more detail before posting. A sparse log is worse than no log — it pollutes search results.
Step 2 — Render the Log
Render the log per prompts/coding/templates/impl-log-template.md.
For Linear, remember comments are sent as literal markdown — real newlines, no escaped \n.
Step 3 — Post the Log
comment(id, renderedLog) via the adapter.
Step 4 — Tag the Item impl-logged
addLabel(id, "impl-logged") via the adapter — this lets boards/dashboards/queries filter items that have logs vs. those still missing them. The adapter handles the per-tracker union/merge semantics; do not hand-roll it here.
tracker: local only — also mirror the rendered log to documentation/impl-logs/{id}.md (create the directory if absent), with a header linking back to ../tracker/{id}.md. This gives a flat, grep-friendly corpus of all impl logs — the local equivalent of "search JIRA/Linear/ADO for what exists." Do this unconditionally for local, regardless of the docs setting; for jira/linear/ado this cross-cutting corpus role is instead served by the optional docs mirror below.
Step 5 — Mirror to the Docs Surface (when a docs backend is configured)
If docs is configured, publish the log to the docs surface via the docs adapter's publishRecord (skills/feature-spec-author/references/docs-adapter.md):
- docs=notion → a row in the Impl Logs database; body = the rendered markdown.
- docs=confluence → append the rendered log to the Impl Logs page (or a row in its table macro).
- docs=ado-wiki → append the rendered log to the Impl Logs wiki page (a row in its table) under
{root}/ImplLogs.
- docs=local → already covered by Step 4 for
tracker: local; for other trackers, append to documentation/impl-logs/{id}.md.
- If the Impl Logs surface doesn't exist yet, do not silently skip — tell the caller to provision it (
confluence-space-manager / notion-workspace-manager for their respective backends). The tracker comment (Step 3) is the system of record regardless.
Step 6 — Return
Return to caller:
- Tracker comment URL/id
- Confirmation that the item is labelled
impl-logged
- Docs mirror URL/path (if mirrored)
Why Structured Artifacts Matter
Future AI agents will search the tracker before writing new code — JQL text search on JIRA, list_issues + label:impl-logged on Linear (plus an optional Notion mirror), WIQL/work-item search on ADO, grep documentation/impl-logs/ on local. Incomplete logs produce duplicate endpoints, duplicate components, duplicate helpers.
Minimum quality bar:
- If the task created an API endpoint,
apiEndpoints MUST be populated
- If the task created a UI component,
components MUST be populated
- If the task created a class,
classes MUST be populated
- A pure refactor (no new public surface) may have empty artifacts but MUST explain in summary: "Refactor only — no new public surface"
Backfilling Logs
If invoked on a closed item that never got a log:
- Read the item's description and any commits referenced (Linear issues carry a
gitBranchName, e.g. khanm/ont-101-..., useful for git log)
git log --follow and git show to identify files and stats- Infer artifacts from the diff (grep for
def , class , @app.route, React component exports)
- Offer the draft log to the user for confirmation before posting
What This Skill Does NOT Do
- Does not evaluate code quality (that's
clean-code-reviewer)
- Does not change the work item's state or close it (that's the executor)
- Does not write logs to the repo, except the local-tracker mirror described above (deliberately — the tracker is the log surface)
- Does not add commits or run tests
References
skills/task-executor/references/tracker-jira.md · tracker-linear.md · tracker-ado.md · tracker-local.md — the tracker adapter (read this first for tool names and label-union gotchas)prompts/coding/templates/impl-log-template.md — the log content templateprompts/coding/templates/impl-log-artifact-schema.md — the shared artifact schemaskills/feature-spec-author/references/docs-adapter.md — the docs adapter (Step 5, docs mirror)- Companion:
backlog-manager / linear-backlog-manager / ado-backlog-manager / local-backlog-manager (Phase 2), the tracker-specific publishers this skill's logs trace back to
- Origin schema: https://github.com/Pimzino/spec-workflow-mcp
log-implementation tool
Feedback
If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.
If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.
