project-doc-update

name	project-doc-update
description	Triggered when project docs need to be modified, added, deleted, or reorganized. This skill holds the project's doc-organization conventions and writing rules.

Doc organization

Experimental side tracks

If a new technical track affects multiple links among data / training / eval, add a corresponding doc under ExperimentalTracks/, named YYMMDD-track-name.md, and add a link to it in Overview.md.

Shared techniques

If a technique is used by multiple links among data / training / eval, put it under Shared/, named YYMMDD(optional)-tech-name.md, and link to it from each link's relevant doc.

Storyline

The project's main narrative (background, related work, goals) lives under Storyline/, as Introduction.md / RelatedWork.md / Target.md. Overview.md links to these at the top; keep them consistent when editing.

Research notes

Research, comparisons, and decision-rationale docs go under ResearchNotes/, split by topic into subdirectories: Data/ Models/ Training/ Eval/ Benchmarks/ RelatedPapers/. When adding a research note, place the file in the right subdirectory and add a wiki link to it in the index at ResearchNotes/ResearchNotesOverview.md.

Common directories

• If a dataset's description, special processing, or filtering rules grow too large, create a subdirectory under Data/ on demand (e.g. Data/Datasets/<dataset name>/). Each such subdirectory needs an entry doc that links to the rest.
• Same applies to training, eval, and other directories.

Flexibility

• Because research is so varied, no single doc-organization scheme fits every situation. Instead of enumerating every case, the organization should satisfy a few overall rules:

1. Track classification (a) Experimental techniques that span multiple links → ExperimentalTracks/. (b) Experimental techniques scoped to a single link → create a doc or subdirectory under that link.

2. Single doc vs. subdirectory Pick "single doc" vs. "subdirectory with multiple docs" mainly by content length.

3. Entry docs and linking rules (a) Every subdirectory must contain an entry doc that links to the rest of its contents. (b) Whether you create a doc or a subdirectory, there must be a link pointing to the new doc / subdirectory's entry.

4. Periodic experiment-plan tidying In AI research projects, later experiments usually depend on earlier results, so experiment plans need to be tidied periodically: (a) Content confirmed unused / no longer used: move into the Archived folder (create it if missing), and remove all links to that doc. (b) Content confirmed effective: consider merging it into the main line. (c) Same-type experiments: when there are multiple experiments of the same kind, create a subdirectory and use a Records subdirectory to log the series.

Format

• Date format is YYMMDD, e.g. 260203.
• File and directory names contain no spaces; use CamelCase or hyphens (e.g. DataOverview.md, 260203-track-name.md).

Doc writing

Writing rules

• Docs should be concise and clear — no redundant content. For an eval, for instance, you don't need every result artifact path — just the key setup, result numbers, and conclusion.
• For tables:
  • If a table is long-and-thin, prefer laying out horizontally rather than vertically. E.g. if an eval (or a few evals) has many metrics, put one metric per column so the table has few rows.
  • Write the data into the cells directly — don't wrap them in backticks.
• For script files:
  • Scripts meant for the user to run manually should use absolute paths so the user can copy-paste.
• Note: existing docs may not fully follow these rules; you don't need to match them. Follow the rules above when writing.

Doc tidying

• An experimental side track gets merged into the main line: move its doc from ExperimentalTracks/ to Shared/, keep the filename. Update Overview.md accordingly.
• An experimental side track is abandoned: move it to ExperimentalTracks/abandoned/, prepend a header with the reason (one sentence), the date, and links to key findings / data, and remove inbound links from other docs.
• Archiving data-processing / training / eval records: Data/, Training/, Eval/ each have a Records/ subdirectory for implementation changes and runs — one file per change/run, linked from the matching DataOverview.md / TrainingOverview.md / EvalOverview.md. Each Records/ also has an Archived/ subdirectory for stale, useless, or already-summarized records. When tidying is triggered (or the user explicitly asks you to tidy certain records), move those records into the corresponding Archived/ and remove their links from the Overview doc.
• Research-note staleness: if a research note's plan has been abandoned or replaced by newer research, annotate it in the ResearchNotesOverview.md index (e.g. (stale) or (superseded by [[ ]])); move it into an Archived/ subdirectory under ResearchNotes/ when appropriate.