Converting your specifications

A conversion rewrites a specification you already use as a SynC standard: the same requirements, as addressable clauses, with the choices a specifier makes on every project pulled out into datasheet fields. Done well, nothing in the source is lost and nothing is added. Each project then answers the fields instead of editing the text.

Convert documents you have the right to use and change, such as your company’s own master specifications. A converted standard lives in your company library.

The markup guide covers every heading marker and datasheet key. This page covers how to apply them to a document you already have.

Each pass has one job. A pass that both transcribes and improves loses track of what the source actually said.

Pass 1: a faithful conversion

• Keep every requirement in the source, as a clause, a bullet, a table row or a datasheet option.
• Keep the source wording. Don’t modernize, tighten or correct it yet.
• Sections become {toc} headings, obligations become clauses, and explanations become {note} headings.
• Drop the source’s own numbering. SynC numbers the headings. Keep the outline shallow, as described below.
• Keep each instruction to the specifier, for now, as a {note} that starts “Specifier note:”. Pass 2 removes them.
• Keep bracketed choices and blanks as plain text in single brackets, such as [480Y/277 V] [208Y/120 V] [____]. An angle-bracket placeholder such as <Insert product type> is a blank too: write it in square brackets. Pass 2 turns them into fields. Never write [[ in this pass: SynC reads it as the start of a reference.
• Keep a bracketed article or paragraph heading with its brackets in the heading text, such as ## [Spare Parts] {toc}. Pass 2 replaces the brackets with a Required / Not required field under the heading.

Before going on, check the count of clauses, notes and tables against what the source holds.

Pass 2: datasheet fields

• Make a field where the source offers a choice or leaves a blank: bracketed options, blanks to fill in, “insert value”, “select one”, “retain if”, “delete if not required”.
• Make a field for numbers that really vary by project: ratings, sizes, quantities, warranty periods, training hours.
• Don’t make a field for a value fixed by code or by a referenced standard, or for a physical constant.
• Add drawing references and project parameters in this pass too.
• Remove every “Specifier note:”. Keep any fact in it that the reader of the issued specification needs, rewritten as a plain note.

Pass 3: a review report

List what you found but did not change: a withdrawn or superseded referenced standard, a wrong code article, a stale paragraph reference, a typo, a passage copied from another section, values that contradict each other. Give each a proposed correction. Apply corrections only after someone approves them, and save them as their own revision so the change is easy to compare.

The report changes no markup, so pass 3 saves no revision of its own.

SynC numbers every heading, and each one is cited by that number. A clause numbered 3.2.7.2.4.3 is hard to cite and harder to find. Most SynC standards use three levels, occasionally four. A guide specification’s own outline (part, article, paragraph, subparagraph, item) runs deeper, so flatten it as you convert:

• Make the articles the top-level {toc} sections. A part heading such as General, Products or Execution adds a level and little else.
• Fold a lead-in whose items all apply, such as “Provide the following:”, into the items under it, so each item is its own clause at the same level: “Enclosure: NEMA Type …” rather than a child of the lead-in. Folding changes the outline, not the words: keep each item’s wording as the source has it, and keep the lead-in’s own words as a clause at the same level when they say more than “the following”. Where the project picks from the items, don’t fold: see “A list the project picks from” below.
• A titled paragraph that holds several obligations, such as “Steel Slotted Support Systems:”, becomes a {toc} section. One that holds a single obligation is a clause.
• Write short sub-items of one obligation as a bullet list under their clause instead of as headings.

Deeper outlines still save. Use a fifth or sixth level only where the source really nests separate obligations. The check reports any heading deeper than four levels.

Guide specifications mark every choice the specifier makes. Each kind becomes one field.

A bracket around words that are not a choice, such as a defined term, is just text. Keep it.

• A clause for each obligation that could be checked on its own. If a contractor could comply with one part and fail another, they are separate clauses.
• Bullets for the items of one obligation: what to submit, what a nameplate shows, which inspections a test includes. The clause introduces them and they are cited with it.
• A table for values in rows and columns: referenced standards, ratings by size, a schedule.
• A datasheet field only where the project chooses. If every project gets the same answer, it is text.

Guide specifications carry notes addressed to whoever edits them: “Select …”, “Retain this paragraph if …”, “Delete if not required”, advice for one agency or another. A SynC standard is read as issued, so everything in it is read by the contractor.

• Remove an instruction once a field asks its question. Remove instructions about editing the document itself.
• Keep a {note} only where it helps the reader of the issued specification: a definition, the reason for a requirement, what a section covers. A note never tells anyone what they should do.
• List every removed instruction in the review report, so a person can decide whether any of it belongs somewhere else.
• Some instructions carry a rule, such as “not permitted in hazardous locations”. Don’t promote it to a requirement on your own. Keep it out of the text and list it in the report as an open question.

A range needs min and max under options, plus step for continuous values or setpoints for standard ones such as trade sizes and ratings. A scale that runs backwards, such as wire gauge, is a select.

Use the unit the source uses, written as its symbol: A, kA, V, %, Ω, in, mm. In clause text, keep dual units the way the source pairs them, as in “75 mm (3 inches)”.

A field’s label is often read away from its clause, so give each one a label that is unique in the standard: “Material: Liquidtight Connectors”, not thirty fields called “Material”.

• On a range, constraint: min when the value is a floor (“not less than”), max when it is a ceiling, exact when it must match.
• On a checkbox or listbox, any_of when any selected item is acceptable (materials, acceptable manufacturers), all_of when every selected item is required (submittals, listing criteria, features).
• A rating or capacity the product must meet is a floor: current and short-circuit ratings, capacity, thickness, warranty length. A limit it must stay under is a ceiling: resistance, sound level, temperature rise, leakage. A system value is exact: voltage, phase, frequency.
• Leave the constraint out when neither the source nor the quantity makes the direction plain.

With a constraint, the label names only the quantity: “Short-Circuit Current Rating”, not “Minimum Short-Circuit Current Rating”. The page writes out the direction.

Ask where the answer lives.

Never write “Per drawings” or “Manufacturer’s standard” as an option. Those are states a field can be in, not values.

SynC has no conditional fields. When a requirement applies only if another choice was made, say so in the clause, “Where power circuit breakers are selected above, …”, and give its field no default unless the source suggests one.

derived is for a value someone works out from facts already stated, including another field’s answer: an insulation level from the system voltage and the site altitude, a current transformer’s accuracy class from its ratio. Don’t use it to say that a field only applies when another choice is made, and don’t add a Required / Not required field whose answer is only a copy of another field’s.

• A list the project picks from. Keep the introducing clause and the full items as a bullet list, then add a checkbox under the same heading asking which items apply.
• Acceptable manufacturers or products. A checkbox with any_of, plus a text field for others the project allows.
• An optional requirement. A radio with Required and Not required.
• Referenced standards. One table under the clause that requires compliance, not a clause per standard.
• A fact about the project, not the section. Site altitude, seismic design category, adopted building code: write [[parameter: name]] in the sentence instead of asking for it as a field. Reuse an existing parameter name exactly.
• A reference to another section. Keep it as text, as the source words it, and list it in the review report so it can be linked once that section is in SynC.
• A location, route or arrangement only a drawing can show. [[drawing: where to look]] inside the clause.

• A guide specification in Word often marks its instructions to the specifier with a paragraph style, a colour or a review comment rather than words. Treat a paragraph in a note style or note colour as an instruction, even inside a requirement, and read the document’s comments (in a .docx, word/comments.xml): plain text extraction leaves them out.
• Bracketed options may also be marked by colour or shading. The brackets decide; the colour only helps you find them.
• Word list numbering does not appear in the extracted text. A paragraph with its numbering switched off usually continues the paragraph above it.
• In a PDF, page headers, footers and page numbers are not part of the text. Remove them.

Convert a long specification one part at a time, with the same rules for every part, so repeated fields come out identical. Settle the rules before you start. Changing them halfway means redoing the parts already done.

Replace LIBRARY NAME with the library to fill, then give your assistant the prompt and the source file. A finished SynC standard from the same discipline, attached as an example, helps it match your house style. It needs an API key with the permissions listed in API integrations.

Convert the attached specification into a SynC standard, named after
its title, in my company library LIBRARY NAME. Create the library if it does
not exist. Use the company category that fits, and create one only if none
does. If I attached a finished SynC standard, follow its structure.

Before you start, read:
- the markup guide: https://synergyinconstruction.com/wiki/about/standards-markup-syntax.md
- the conversion guide: https://synergyinconstruction.com/help/converting-specifications
  (it ends with this prompt; the rules above it are what to follow)
- the API index: https://synergyinconstruction.com/api/help?format=index

Work in three passes. After each pass, check the markup with
POST /api/standards/validate-markdown, fix every error it reports, then save
it as a new revision so I can review it in SynC, where it renders properly.
Save the first revision with severity "major" so it is numbered 1.0.0, and
later passes as minor revisions.
Stop after each revision and wait for me.
1. A faithful conversion. Keep every requirement and the source wording.
   Add nothing.
2. Datasheet fields for the choices and blanks the source gives the specifier.
3. A review report, with no new revision: counts of sections, clauses, notes
   and fields; the judgment calls I might change; source errors with a proposed
   correction; the specifier instructions you removed; open questions; any new
   parameter names.

Do not fix errors in the text. List them in the report. Apply only the
corrections I approve, and save them as their own revision.