From b38936565679cf256e77a0b7e85d1d4cce3ff270 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B8=D1=85=D0=B0=D0=B8=D0=BB=20=D0=9A=D0=B0=D0=BF?= =?UTF-8?q?=D0=B5=D0=BB=D1=8C=D0=BA=D0=BE?= Date: Sat, 17 Oct 2026 19:22:21 +0300 Subject: [PATCH] skil --- AGENTS.md | 8 +++++ docs/file-summary.md | 77 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/file-summary.md diff --git a/AGENTS.md b/AGENTS.md index 16dbfbd..ed77795 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -169,3 +169,11 @@ generated `dialect.swift`). Do not flip it on without addressing those. - The generated UI callback plumbing is nonisolated; UI singletons are weak (`RootComponent.singleton`, `RootVM.shared`) and are accessed from the generated oneliners with force-unwrap (`RootVM.shared!.countText = ...`). + +## Skill: source-file study documents + +When the task is to produce a source-code study document — a self-contained, +downloadable HTML file with a line-by-line table of the file and its +explanations (and, on request, a second version highlighting changes after a +fix) — follow the skill in `docs/file-summary.md`. + diff --git a/docs/file-summary.md b/docs/file-summary.md new file mode 100644 index 0000000..f5345ec --- /dev/null +++ b/docs/file-summary.md @@ -0,0 +1,77 @@ +# Exported tables with a source-file breakdown + +This document describes preparing a self-contained HTML file for studying source +code in a browser: a line-by-line table with explanations and, if needed, a +separate version after the code has been changed. + +## Source code and explanations + +1. Use the exact version of the file the user requested. For the version prior to + a fix, obtain the contents from the corresponding Git revision rather than + substituting the current file. State the file name and the source revision in + the document. +2. Keep every line of the source, their order, the original numbers, blank lines + and indentation. Do not shorten expressions or reformat code for the sake of + the table. +3. Create three columns: line number, source line, explanation. +4. If the breakdown was already given in the conversation, carry over the original + explanations verbatim. Do not replace them with an abridged retelling or new + wording. Preserve the highlighting and notation from the code. +5. Do not add obvious explanations such as "Ends the block", "Continuation of the + declaration" or descriptions of blank lines. Leave such cells empty. +6. Place the explanation for several lines in a single vertically merged cell of + the third column via `rowspan`. Keep the individual numbers and code of each + line in the first two columns. + +## HTML formatting + +1. The result is a separate downloadable `.html` file opened in a browser. Keep + all syntax highlighting and styling inside the file, with no external + libraries, fonts, network requests or other external dependencies. +2. Put the code in `
`, preserving the original spaces and indentation.
+   Escape HTML special characters so that the displayed code matches the source.
+3. Include syntax highlighting for the relevant language. For Swift, distinguish
+   keywords, types, strings, comments, numbers and directives.
+4. Make the second and third columns equal in width. Keep the number column
+   narrow; it does not take part in splitting the remaining space in half.
+5. Allow long code lines to wrap while preserving the original indentation:
+   `white-space: pre-wrap` and `overflow-wrap: anywhere`. Do not require
+   horizontal scrolling to read long expressions.
+6. Do not use alternating coloured row shading.
+7. Align the horizontal separators in the code and explanation columns. When an
+   explanation is merged, remove the internal lines between the corresponding
+   code lines: the borders must separate the same semantic groups.
+8. Do not draw horizontal lines before completely blank lines: visually they abut
+   the preceding fragment.
+9. Do not draw horizontal lines before lines with an empty explanation, including
+   non-empty code lines. They visually continue the previous group.
+10. Preserve the readability of the highlighting, the wrapping and the equal
+    column widths when changing the formatting; editing one property must not
+    undo the others.
+
+## Separate version after the fix
+
+1. On request, create a second HTML file with the changed version of the source.
+   Keep the first file with the version prior to the fix.
+2. Use the line numbers of the new version. Compare it against the explicitly
+   stated source revision and determine the lines that were actually added and
+   changed.
+3. Highlight in green only the numbers of the new and changed lines in the first
+   column. Do not colour entire table rows, the code background or the
+   explanations. Keep the normal code syntax highlighting.
+4. For unchanged fragments, keep the original explanations verbatim. For the new
+   code, add explanations of its purpose and how it works.
+5. Apply the same requirements for indentation, wrapping, column widths,
+   explanation merging and horizontal separators to both files.
+
+## Verification and handoff
+
+1. Verify that the lines and numbering match the chosen version of the source.
+2. Verify that the original explanations are verbatim and that there are no
+   obvious boilerplate comments instead of substantive explanations.
+3. Verify that `rowspan` is correct, the column borders line up, the code wraps,
+   there is no striped shading, and changes are highlighted only in the number
+   column.
+4. Make sure the HTML is fully self-contained, and give the user a link to the
+   file. When updating an already open document, tell the user the page needs to
+   be refreshed.