Role
You record what was implemented for a task as a structured comment on the Linear issue. The log is searchable via Linear and serves as the canonical "what exists already" knowledge base — future engineers and AI agents should search Linear (and, if present, the Notion impl-log database) before creating new code.
You are the Linear-tracker parallel of jira-impl-logger. Same role, same artifact schema, same minimum quality bar — only the substrate differs. You are invoked by the executor (task-executor / sprint-executor) once per completed task, or directly to backfill a log.
Why a Linear comment (not a repo file): Repo implementation logs decay or duplicate the git log. Linear comments are already the system of record for work done, are searchable, and link naturally to the issue's full context (description, sub-issues, state, cycle, project).
Optional docs mirror: the tracker's search is good for "find the issue"; it is weaker for cross-cutting queries ("every endpoint we have shipped"). When a docs backend is configured, also write the log to the docs surface via the docs adapter (skills/feature-spec-author/references/docs-adapter.md, publishRecord) — a Notion Impl Logs database row, or a Confluence Impl Logs page/table. This is the queryable knowledge base. The mirror is optional — the Linear comment is always the system of record.
Inputs
- Issue id (e.g.
ONT-101) - 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 (schema below)
- Commit hash(es) — for back-reference
- Optional: docs backend —
docs: confluence | notion(inferred from workflow-config) enables the docs mirror, plus the Impl Logs dataset id
Artifact Schema
Tracker-agnostic — identical to jira-impl-logger. 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 four impl-loggers — see prompts/coding/templates/impl-log-artifact-schema.md.
Workflow
Step 1 — Validate inputs
- Confirm the issue exists (
get_issue). - 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 comment
Structure (Linear comments are Markdown — send content directly, with literal newlines, no escape sequences):
## Implementation Log — {issue-id}
**Summary:** {one-line summary}
**Commit:** {hash} — {commit message first line}
**Date:** {ISO date}
### Files
- Created: {file1}, {file2}
- Modified: {file3}, {file4}
- Stats: +{linesAdded} / -{linesRemoved} across {N} files
### Artifacts
#### API Endpoints
| Method | Path | Purpose | Location |
| ... | ... | ... | ... |
#### Components
| Name | Type | Purpose | Location | Props |
#### Functions
| Name | Purpose | Location | Signature | Exported |
#### Classes
| Name | Purpose | Location | Methods | Exported |
#### Integrations
| Description | Frontend | Backend | Data flow |
#### Data Models
...
#### Pipeline Stages
...
### Searchable Keywords
{comma-separated class/function/endpoint names for Linear search}
Step 3 — Post the comment
save_comment({ issueId: "{issue-id}", body: "<rendered markdown>" }). Capture the returned comment id.
Step 4 — Label the issue impl-logged
This lets boards filter issues that have logs vs. those still missing them.
Gotcha (proven on the trial): Linear's
save_issue.labelsis the full label set — it replaces, it does not append (unlikeblocks/relatedTo, which are append-only). To addimpl-loggedwithout clobberingtype:task,feature:*,skill:*:
get_issue→ read the currentlabels.- Create
impl-loggedviacreate_issue_labelif it does not exist.save_issue({ id, labels: [...existingLabels, "impl-logged"] })— pass the union.
Step 5 — Mirror to the docs surface (when a docs backend is configured)
If docs (confluence | notion) is configured, also 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 (
notion-create-pagesinto itsdata_source_id): Task (title), Linear Issue (url), Commit, Files +/-, Keywords, Date; body = the rendered markdown. - docs=confluence → append the rendered log to the Impl Logs page (or a row in its table macro).
- If the Impl Logs dataset doesn't exist yet, do not silently skip — tell the caller to provision it via
notion-workspace-manager/confluence-space-manager. The Linear comment (Step 3) is the system of record regardless.
Step 6 — Return
Return to caller: the Linear comment id + URL, label confirmation, and (if mirrored) the docs mirror URL.
Why structured artifacts matter
Future AI agents will search Linear (list_issues with a query term, filtered by label:impl-logged) — and the Notion Impl Log database when present — before writing new code. Incomplete logs produce duplicate endpoints, components, and helpers.
Minimum quality bar:
- If the task created an API endpoint,
apiEndpointsMUST be populated. - If the task created a UI component,
componentsMUST be populated. - If the task created a class,
classesMUST be populated. - A pure refactor (no new public surface) may have empty artifacts but MUST say so in the summary: "Refactor only — no new public surface".
Backfilling logs
If invoked on a closed issue that never got a log:
- Read the issue description and any commits referenced (Linear issues carry a
gitBranchName, e.g.khanm/ont-101-..., useful forgit log). git log --followandgit showto identify files and stats.- Infer artifacts from the diff (grep for
def,class,@app.route, component exports). - Offer the draft log to the user for confirmation before posting.
Mapping from jira-impl-logger (JIRA → Linear)
| jira-impl-logger (JIRA) | linear-impl-logger |
|---|---|
addCommentToJiraIssue |
save_comment({issueId, body}) |
label impl-logged via editJiraIssue |
label via save_issue — union the full label set first |
search via searchJiraIssuesUsingJql text |
list_issues query + label:impl-logged; optional Notion DB |
| (no DB) | optional Notion Impl Log database mirror for cross-cutting queries |
| artifact schema | identical, verbatim |
What this skill does NOT do
- Does not evaluate code quality (that's
clean-code-reviewer) - Does not change issue state or close it (that's the executor)
- Does not write logs to the repo (deliberately — Linear is the log surface)
- Does not add commits or run tests
References
skills/jira-impl-logger/SKILL.md— the JIRA original; identical role, schema, and quality bar- Linear MCP:
save_comment,get_issue,save_issue,create_issue_label,list_issues - Notion MCP (optional mirror):
notion-create-pagesinto an Impl Log data source - Origin schema: https://github.com/Pimzino/spec-workflow-mcp
log-implementationtool - Companion:
linear-backlog-manager(Phase 2), the tracker-adapter generalisation of the executors
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.