SuperAPI AI Directory

linear-impl-logger

Coding & development

View repository

Updated 10-16 02:39

About this skill

Linear Implementation Logger

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.labels is the full label set — it replaces, it does not append (unlike blocks/relatedTo, which are append-only). To add impl-logged without clobbering type:task, feature:*, skill:*:

  1. get_issue → read the current labels.
  2. Create impl-logged via create_issue_label if it does not exist.
  3. 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-pages into its data_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, 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 say so in the summary: "Refactor only — no new public surface".

Backfilling logs

If invoked on a closed issue that never got a log:

  1. Read the issue description and any commits referenced (Linear issues carry a gitBranchName, e.g. khanm/ont-101-..., useful for git log).
  2. git log --follow and git show to identify files and stats.
  3. Infer artifacts from the diff (grep for def , class , @app.route, component exports).
  4. 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-pages into an Impl Log data source
  • Origin schema: https://github.com/Pimzino/spec-workflow-mcp log-implementation tool
  • 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.