From 04a0d93c1fff353535c05b168a8dbf637645a128 Mon Sep 17 00:00:00 2001 From: Matic Jurglic Date: Fri, 10 Jul 2026 12:15:49 +0200 Subject: [PATCH 1/4] Dedupe SEARCH/REPLACE editing instructions into source-code-editing (CS-12028) Make skills/source-code-editing/SKILL.md the single authority for the SEARCH/REPLACE spec: fold the .gts edit-tracking convention into it, point the Skill card's instructionsSource at it (deleting the drifted Skill/source-code-editing.md copy), and reduce Skill/dev-file-editing.md and skills/boxel/references/file-editing.md to pointers. Co-Authored-By: Claude Fable 5 --- Skill/boxel-development.json | 2 +- Skill/dev-file-editing.json | 2 +- Skill/dev-file-editing.md | 89 ++---------------- Skill/source-code-editing.json | 4 +- Skill/source-code-editing.md | 114 ------------------------ skills/boxel/SKILL.md | 2 +- skills/boxel/references/file-editing.md | 90 ++----------------- skills/source-code-editing/SKILL.md | 46 +++++++++- 8 files changed, 66 insertions(+), 283 deletions(-) delete mode 100644 Skill/source-code-editing.md diff --git a/Skill/boxel-development.json b/Skill/boxel-development.json index 952a970..24156cb 100644 --- a/Skill/boxel-development.json +++ b/Skill/boxel-development.json @@ -49,7 +49,7 @@ }, { "inclusionMode": "full", - "contentSummary": "SEARCH/REPLACE essentials, tracking mode, creating/modifying files, best practices", + "contentSummary": "Pointer to the Source Code Editing skill (SEARCH/REPLACE format, edit-tracking convention)", "alternateTitle": "File Editing" }, { diff --git a/Skill/dev-file-editing.json b/Skill/dev-file-editing.json index 2040007..eb2326b 100644 --- a/Skill/dev-file-editing.json +++ b/Skill/dev-file-editing.json @@ -11,7 +11,7 @@ "cardInfo": { "notes": null, "name": "File Editing", - "summary": "SEARCH/REPLACE patterns and tracking mode for code generation", + "summary": "Pointer to the Source Code Editing skill, which defines the SEARCH/REPLACE format and edit-tracking convention", "cardThumbnailURL": null }, "commands": [] diff --git a/Skill/dev-file-editing.md b/Skill/dev-file-editing.md index ff94764..4ae25cc 100644 --- a/Skill/dev-file-editing.md +++ b/Skill/dev-file-editing.md @@ -1,85 +1,10 @@ -### SEARCH/REPLACE Essentials +# File Editing -**Every .gts file line 1:** -```gts -// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══ -``` +The SEARCH/REPLACE block format and the `.gts` edit-tracking convention (line-1 banner, `// ⁿ` markers) are defined in the canonical **Source Code Editing** skill (`skills/source-code-editing/SKILL.md`), not here. Consult that skill before editing or creating any file. -**Creating new file:** -```gts -http://realm/card.gts (new) -╔═══ SEARCH ════╗ -╠═══════════════╣ -// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══ -import { CardDef } from '...'; // ¹ -export class MyCard extends CardDef { } // ² -╚═══ REPLACE ═══╝ -``` -╰ ¹⁻² +Key reminders: -**Modifying existing:** -```gts -https://realm/card.gts -╔═══ SEARCH ════╗ -existing code with tracking markers -╠═══════════════╣ -modified code with new markers // ⁵ -╚═══ REPLACE ═══╝ -``` -⁰ ⁵ - -## File Editing System - -### Tracking Mode - -**MANDATORY for .gts Files:** -1. All `.gts` files require tracking mode indicator on line 1: - ```gts - // ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══ - ``` -2. Format: `// ⁿ description` using sequential superscripts: ¹, ², ³... -3. Both SEARCH and REPLACE blocks must contain tracking markers - -### SEARCH/REPLACE Patterns - -#### Creating New File -```gts -http://realm/recipe-card.gts (new) -╔═══ SEARCH ════╗ -╠═══════════════╣ -// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══ -import { CardDef } from 'https://cardstack.com/base/card-api'; // ¹ -export class RecipeCard extends CardDef { // ² - static displayName = 'Recipe'; -} -╚═══ REPLACE ═══╝ -``` -⁰ ¹⁻² - -#### Modifying Existing File -```gts -https://example.com/recipe-card.gts -╔═══ SEARCH ════╗ -export class RecipeCard extends CardDef { - static displayName = 'Recipe'; - @field recipeName = contains(StringField); -╠═══════════════╣ -export class RecipeCard extends CardDef { - static displayName = 'Recipe'; - @field recipeName = contains(StringField); - @field servings = contains(NumberField); // ¹⁸ Added servings -╚═══ REPLACE ═══╝ -``` -⁰ ¹⁸ - -### File Type Rules - -- **`.gts` files** → ALWAYS require tracking mode and markers -- **`.json` files** → Never use tracking comments - -### Best Practices - -- Keep search blocks small and precise -- Include tracking comments in SEARCH blocks for uniqueness -- Search text must match EXACTLY -- Use placeholder comments for easy insertion points \ No newline at end of file +- ALWAYS use SEARCH/REPLACE for `.gts` files — never `write-text-file`. +- Every `.gts` file starts with the `// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══` banner; mark changed lines with sequential `// ⁿ` superscript comments. `.json` files never get tracking comments. +- For new files, append `(new)` after the file URL line. +- SEARCH text must match the existing file exactly; keep blocks small. diff --git a/Skill/source-code-editing.json b/Skill/source-code-editing.json index 5b09790..9d8acb7 100644 --- a/Skill/source-code-editing.json +++ b/Skill/source-code-editing.json @@ -26,11 +26,11 @@ }, "instructionsSource": { "links": { - "self": "./source-code-editing.md" + "self": "../skills/source-code-editing/SKILL.md" }, "data": { "type": "file", - "id": "./source-code-editing.md" + "id": "../skills/source-code-editing/SKILL.md" } } } diff --git a/Skill/source-code-editing.md b/Skill/source-code-editing.md deleted file mode 100644 index 62c67a0..0000000 --- a/Skill/source-code-editing.md +++ /dev/null @@ -1,114 +0,0 @@ -# Source Code Editing - -When you infer that the user wants to make changes to the attached files, which is usually a card definition, or create new files, you must use a SEARCH/REPLACE block. For .gts files, ALWAYS use SEARCH/REPLACE — never use write-text-file for .gts. SEARCH/REPLACE blocks stream as visible text (the user sees progress), while tool calls like write-text-file do NOT stream (the UI appears frozen with "Thinking" / "Preparing tool call" while generating the full file content). - -A SEARCH/REPLACE block has 2 sections: a section of code to search for, and the code to replace it with. All code within the SEARCH will be replaced. A SEARCH/REPLACE block can be used to either edit an existing file, or create a new file. - -This is ABSOLUTELY CRUCIAL, WITHOUT THIS THE CODE PATCH WON'T WORK: in the beginning of the code block, before ╔═══ SEARCH ════╗ marker, add a line with the file url. If you are editing, this should be the attached file's url. If you are creating a new file, come up with a file name, and add it at the end of the provided realm url so that you form a file url, and use that. - -Example adding an import: - -```gts -https://example.com/attached-file-example.gts -╔═══ SEARCH ════╗ -import { Component } from 'https://cardstack.com/base/card-api'; -import { or } from '@cardstack/boxel-ui/helpers'; -╠═══════════════╣ -import { Component } from 'https://cardstack.com/base/card-api'; -import { MarkdownField } from 'https://cardstack.com/base/markdown'; -import { or } from '@cardstack/boxel-ui/helpers'; -╚═══ REPLACE ═══╝ -``` - -Example deleting a field by not including it in the replace block: - -```gts -https://example.com/attached-file-example.gts -╔═══ SEARCH ════╗ - @field description = contains(StringField); - @field categories = containsMany(Category); - @field attemptsRemaining = contains(NumberField, { - computeVia: function() { - return 4; // Start with 4 attempts - } - }); -╠═══════════════╣ - @field description = contains(StringField); - @field categories = containsMany(Category); -╚═══ REPLACE ═══╝ -``` - -Example changing text within a template: - -```gts -https://example.com/attached-file-example.gts -╔═══ SEARCH ════╗ -