fix(#193): add ADR-awareness steps to code-implementation skill

[fullsend-ai-coder]

Add two changes to the code-implementation skill so the code agent checks Architecture Decision Records during planning:

1. Step 3 substep 1: mention checking for an ADR directory
   (docs/ADRs/, adr/, docs/architecture/decisions/) so the agent
   knows to consult them later in step 8.

2. Step 8: insert new substep 5 after "Follow cross-repo
   references" instructing the agent to search ADR files for
   keywords matching the area being changed. If an ADR constrains
   the approach, the agent must follow the ADR over ad-hoc issue
   recommendations. Renumber subsequent substeps (5-9 become
   6-10).

This prevents wasted code-review-fix cycles when an issue's recommended approach conflicts with an accepted ADR, as happened with ADR 43 on PR fullsend-ai#2578 in fullsend-ai/fullsend.

Note: pre-commit could not run fully due to shellcheck-py network restrictions in the sandbox. Individual hooks (end-of-file-fixer, trailing-whitespace, lint-md-links) passed.

---

Closes #193

Post-script verification

• Branch is not main/master (agent/193-adr-awareness-planning)
• Secret scan passed (gitleaks — f96750babbed5ada406a9ae04e8068449701d9c7..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[fullsend-ai-review]

Review

Findings

Low

• [internal-consistency] internal/scaffold/fullsend-repo/skills/code-implementation/SKILL.md — Step 3 substep 1 enumerates three ADR directory conventions (docs/ADRs/, adr/, docs/architecture/decisions/) for the agent to discover, but step 8 substep 5 only explicitly names docs/ADRs/ and defers to "(or equivalent, if noted in AGENTS.md)". If AGENTS.md does not mention the ADR directory and the repo uses adr/ or docs/architecture/decisions/, the agent may not carry forward its step 3 discovery to step 8. Consider repeating all three conventions in step 8 substep 5 or referencing "the ADR directory discovered in step 3" so the agent carries forward its earlier discovery.

Previous run

Looks good to me

Previous run (2)

Review — Approve

PR: #215 — fix(#193): add ADR-awareness steps to code-implementation skill
Author: fullsend-ai-coder[bot]
Scope: 1 file changed (internal/scaffold/fullsend-repo/skills/code-implementation/SKILL.md), +22 −9

Summary

This PR adds two ADR-awareness instructions to the code-implementation skill so the code agent checks Architecture Decision Records during planning, preventing wasted review-fix cycles when an issue's recommended approach conflicts with an accepted ADR.

Changes verified

1. Step 3 substep 1 (Discover repo conventions): Adds a forward reference instructing the agent to check for an ADR directory (docs/ADRs/, adr/, or docs/architecture/decisions/) during project discovery, with a pointer to step 8 where ADRs are consulted.

2. Step 8 new substep 5 (Plan the implementation): Inserts a new substep "Check relevant Architecture Decision Records" after substep 4 ("Follow cross-repo references"). The instruction directs the agent to search ADR files with Grep for keywords matching the area being changed, and explicitly establishes that accepted ADRs supersede ad-hoc issue recommendations. Subsequent substeps are renumbered correctly (5→6, 6→7, 7→8, 8→9, 9→10).

Review dimensions

Dimension	Assessment
Correctness	✅ Renumbering is accurate. The step 3 forward reference to "step 8" follows the existing convention of referencing major steps (cf. step 3 substep 4 → "step 10"). The new substep 5 content is well-formed and actionable. No edge cases or logic errors.
Security	✅ Documentation-only change. No code, no secrets, no privilege changes. PR body is clean — no injection patterns detected.
Intent & coherence	✅ The change precisely matches the scope authorized by issue #193, including the exact proposed text. The motivation (ADR 43 violation on PR fullsend-ai#2578) is well-documented and the fix directly addresses the root cause.
Style/conventions	✅ Follows the existing markdown formatting patterns: bold substep title, em dash separator, prose description. Indentation adjusts correctly for double-digit list item (10).
Documentation currency	✅ This is the documentation change. The forward reference in step 3 and the new substep in step 8 are internally consistent. No other documents reference the old substep numbers.
Cross-repo contracts	✅ This is a scaffold skill file deployed to downstream repos. The new step is additive and conditional ("if the repo has a docs/ADRs/ directory"), so repos without ADRs are unaffected. Backward compatible.

Findings

No findings at severity low or above.

---

Labels: PR modifies a scaffold skill document (code-implementation)

Previous run (3)

Review — PR #215

Summary

This PR adds ADR-awareness to the code-implementation skill, addressing issue #193. The change is well-scoped: it modifies only internal/scaffold/fullsend-repo/skills/code-implementation/SKILL.md (+22/−9) to insert an ADR-checking substep into step 8's planning phase and a forward-reference in step 3's discovery phase.

Scope & authorization: The diff matches the issue's proposal exactly — no scope creep. The new substep 5 and the step 3.1 addition are precisely what #193 requested.

Correctness: Step numbering is correct (old 5–9 → new 6–10, no gaps or duplicates). The step 3.1 forward-reference to "step 8" correctly points to the parent step "Plan the implementation." No external documentation references the renumbered substeps, so no stale cross-references. Logical placement (after "Follow cross-repo references," before "Identify what to change") is sound — ADR constraints should be understood before deciding what to change.

Security: No findings. Clean docs-only change with no secrets, injection patterns, steganographic content, or permission changes.

Style: The new text follows all established formatting conventions — bold headers with em dash separators, 3-space continuation indentation, lowercase "step N" cross-references.

Findings

1. Inaccurate AGENTS.md reference in scaffold template — medium

File: internal/scaffold/fullsend-repo/skills/code-implementation/SKILL.md, new substep 5 (~line 307)
Category: technical-accuracy

The new substep states:

if the repo has a docs/ADRs/ directory (or equivalent, as noted in AGENTS.md)

The scaffold's AGENTS.md template (internal/scaffold/fullsend-repo/AGENTS.md) contains no mention of ADRs, ADR directories, or architecture decision records. It covers only: think before acting, simplicity first, surgical changes, commit message format, and goal-driven execution. The fullsend repo's root AGENTS.md has an ADR section, but that is repo-specific — not part of the template deployed to user repos.

When deployed to a repo whose AGENTS.md lacks ADR guidance (the default case using the scaffold), an agent following this instruction literally will look for ADR information "as noted in AGENTS.md" and find nothing, which is confusing.

Impact: Limited — the primary instruction ("if the repo has a docs/ADRs/ directory") works regardless. The parenthetical adds optional context, not a gate.

Remediation: Soften to (or equivalent, if noted in AGENTS.md) to make the reference conditional, or remove the parenthetical and rely on the directory name heuristic alone.

2. Commit type is defensible but borderline — low

File: PR title
Category: commit-convention

The PR uses fix(#193): but per COMMITS.md, this change straddles fix and refactor. The fix prefix is for "Bug fix visible to users" and refactor is for "Code restructuring (no behavior change)." COMMITS.md allows both for "tuning agent behavior that users don't directly control" when it corrects a defect. Since issue #193 describes a real procedural gap that caused wasted cycles, fix is defensible. However, the PR adds a step rather than fixing broken logic, which leans toward refactor.

No action required — fix is within the project's guidelines.

Verdict

comment — One medium finding (AGENTS.md reference accuracy) worth noting but not blocking. The implementation is correct, well-scoped, and architecturally sound.

[guyoron1]

/fs-review

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:19 AM UTC · Completed 10:27 AM UTC
Commit: a2afa8b · View workflow run →

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 11:12 AM UTC · Completed 11:20 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed 1 review finding: softened the AGENTS.md reference in the new ADR-awareness step from assertive ('as noted in') to conditional ('if noted in'). The scaffold AGENTS.md template contains no ADR directory information, confirming the reviewer's technical-accuracy concern.

Fixed (1):

1. AGENTS.md reference is assertive but scaffold template has no ADR info (internal/scaffold/fullsend-repo/skills/code-implementation/SKILL.md): Changed 'as noted in AGENTS.md' to 'if noted in AGENTS.md' in the new ADR-awareness substep (step 5 line 308). The scaffold AGENTS.md template does not mention ADR directories, so the reference should be conditional rather than assertive.

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 11:26 AM UTC · Ended 11:37 AM UTC
Commit: a2afa8b · View workflow run →