electrical_engineering_reports v1.0.0

name: "electrical_engineering_reports" description: "Write electrical engineering documents around verified numbers: Division 26 specifications, load and design reports, and short circuit, coordination, and arc flash study write-ups where every value traces to a calculation, a nameplate, a schedule, a code table, or a labelled assumption. Use when drafting or checking a specification section, a load calculation report, a basis of design, or a power study summary, or when any number in an electrical document cannot be sourced."

Electrical Engineering Reports

Purpose

Turn schedules, nameplates, field notes, and calculation runs into electrical engineering documents a reviewer can sign: a specification where each rating the design relies on is a rating the project actually checked, a load report where connected, demand, and sizing loads stay separate and labelled, and a study write-up where each fault current, setting, and incident energy value traces to the run that produced it. Anything that cannot be verified stays visible as a flagged assumption with a basis and a closing event. A flagged document can be fixed. A document with a borrowed fault current, a demand factor from the wrong code edition, or an incident energy value copied from a similar building reads as finished and fails later, at the gear, in the field, or after an incident.

This is process guidance, not engineering judgment and not a substitute for the adopted code. Design decisions, study conclusions, and signing and sealing belong to the licensed engineer in responsible charge of the work, under the board rules of the state where the work sits. This skill builds and checks the paperwork around those decisions, and it names the edition, the basis, and the assumption on the face of each document so the engineer can judge them.

Workflow

1. Build the value tracing sheet before drafting anything. One row per load bearing value in the form of assets/value-tracing-sheet.csv: id, value, unit, where it appears in the report, source type, and the source itself in enough detail to find it again. Allowed source types are calculation, code, standard, nameplate, field, schedule, manufacturer, utility, quote, and assumption. A value with no row does not go into the document. A value whose source has not arrived goes in as an assumption row, with its basis and the event that closes it, and the document prints it as open. Work the full method in references/checklists.md under value tracing check.
2. Fix the governing editions and criteria on the first page. Name the NEC edition adopted by the authority having jurisdiction, the NFPA 70E and IEEE 1584 editions the project criteria name, the study standard each study follows, and the project criteria that adopt code recommendations as project rules. Read every demand factor, unit load, and table value from those editions. Table numbering and values change between editions, so a factor carried over from a prior edition or a prior project is a flag, not a value.
3. Write specifications in their MasterFormat and SectionFormat place. Electrical work sits in Division 26, with sections such as 26 05 00 Common Work Results for Electrical read from the project manual table of contents, never typed from memory. Each section follows CSI SectionFormat: Part 1 General carries scope, references, submittals, and quality assurance, Part 2 Products carries materials, manufacturers, and the ratings the design relies on, and Part 3 Execution carries installation and field quality control. The worked excerpt in assets/worked-spec-260500.md shows the shape, including the move that makes the rest of this skill enforceable in construction: Part 1 writes the calculation package, tracing sheet included, into the submittals, so a package without its sheet is incomplete on its face.
4. Keep ratings in a specification honest and few. A Part 2 rating enters the section only when the design relies on it and the calculation package or the product data traces it, the way the worked excerpt traces its one product rating to the example data sheet as T-037. Delete ratings copied in from a guide specification that this project never checked. A long rating list copied for safety makes review harder and hides the three ratings that matter among thirty that do not.
5. Build a load report from the schedules, and keep its three loads separate. List the connected loads from the panel schedules and equipment data, each one traced. Apply the demand factors from the adopted edition to reach the demand load. Build the sizing load by applying the continuous load factor to the continuous portions: NEC Article 220 practice sizes feeders at the noncontinuous load plus 125 percent of the continuous load, traced in the worked report as T-010. List noncoincident loads such as cooling and heating, state which one was taken, and show the one left out. In the worked report in assets/worked-load-report.md, a demand load of 101000 VA as T-006 and a sizing load of 110000 VA as T-007 produce a demand current of 121.49 A as T-008 and a sizing current of 132.31 A as T-009 at the traced system voltage. Label which current each later check uses, every time.
6. Calculate with the shipped calculator and file its output. Run python3 scripts/ee_calcs.py for load current, sizing load, voltage drop, and transformer full load and fault estimates. Each subcommand prints its inputs, the formula it used, and the result. Paste that output into the project file behind the report and cite the run on the tracing row, as the worked rows T-008, T-009, T-015, and T-031 do. A result whose run output is not filed is a typed number, and a typed number is what this skill exists to prevent.
7. Run voltage drop on the demand current, on the built route, against the project criterion. Use VD = 2 x K x I x L / CM for single phase and VD = 1.732 x K x I x L / CM for three phase, with L as the one way length in feet, CM as the conductor area from NEC Chapter 9 Table 8 in the adopted edition, and K at 12.9 for copper and 21.2 for aluminum. The NEC informational notes at 210.19 and 215.2 recommend a maximum of 3 percent on a branch circuit or a feeder and 5 percent for feeder and branch combined. Those notes are recommendations in the code and become binding on the project only when the project criteria adopt them, and some loads carry mandatory limits in their own articles that override the notes, so read the article that governs the load before quoting a limit. Show each conductor tried, not only the winner: in the worked branch check the smallest conductor drops 5.27 percent as T-024 and fails the adopted branch criterion, the middle conductor drops 3.31 percent as T-026 and also fails, and the largest drops 2.08 percent as T-028 and passes. A report that shows only the passing try hides how close the decision was.
8. Select conductors on ampacity as a separate check from voltage drop, and say so. Take the ampacity from the table in the adopted edition, in the column that matches the termination temperature rating, after ambient correction and conductor count adjustment where they apply. State the table, the column basis, and the factors, or flag those inputs as open the way the worked load report does. A conductor can pass ampacity and fail voltage drop, as the worked branch check proves, so a report that runs one check and presents it as both is wrong in a way a reviewer cannot see without rerunning the work.
9. State the short circuit basis before any fault number. Open the study write-up with its basis: the utility fault letter with its date and value, or the stated alternative basis flagged as an assumption. List the contributions the model includes, with transformer rating and percent impedance from nameplates, conductor material, size, and length, and motor and generator contribution where the study method includes it. Follow a named study standard, such as IEEE 3002.3 for short circuit studies, and state the fault type modelled. In the worked summary in assets/worked-study-summary.md, a transformer rated 750 kVA as T-029 with percent impedance 5.75 percent as T-030 gives a full load current of 902.14 A as T-031 and, on the flagged infinite bus basis recorded as assumption T-038, a bolted fault current of 15.69 kA as T-033 from scripts/ee_calcs.py transformer. The summary prints that basis in the same paragraph as the result and refuses to call the study final while the assumption row is open.
10. Check interrupting and withstand ratings bus by bus, against the adopted code rule. NEC 110.9 asks that equipment intended to interrupt current at fault levels have an interrupting rating at nominal circuit voltage at least equal to the current available at its line terminals, and NEC 110.10 asks that protective devices, total impedance, and component short circuit current ratings be selected and coordinated so a fault does not cause extensive damage. Present results in a per bus table: bus name matching the drawings, voltage, device with type and rating, and calculated current at that bus. Check each device against its own bus value, the way the worked summary checks its example switchboard rating of 22 kA as T-034 against the fault current at that gear. Never check a downstream device against the service value, and never average fault currents across buses into one tidy system value. Record the service equipment fault current field marking, with the calculation date on the marking, where the adopted code asks for it under 110.24.
11. Write the coordination write-up from the curve files, and report the trade offs. Plot each fault path on a common voltage base with time current curves for the device nearest the fault and each device upstream, including the utility device where it applies, transformer damage and inrush points, and motor starting points where a motor sits in the path. Read separation at both the maximum and the minimum fault current for the path. State each recommended setting with the device it belongs to and the curve file that supports it, and carry no setting the curve file does not show. Where protection and selectivity conflict, IEEE 242 practice treats the choice as a real decision: state which one was favoured, why, and what the other choice would have cost. List any path where full selectivity was not achieved as a finding with its consequence. Close with the field step: settings read back from the installed devices and compared with the study before the study is called final.
12. Write the arc flash write-up from the model run, or write it with the values absent. Use the IEEE 1584 edition named in the project criteria and confirm each bus falls inside that edition's stated scope and validity limits, giving buses outside the limits a stated alternative method. Trace each model input to its source: bolted fault current from the short circuit study, clearing time from the coordination curves for that bus, electrode configuration, gap, enclosure information, and working distance, each from its named input sheet. Never reproduce a prior edition's equations as a current hand method, never borrow an incident energy value from a prior study or a similar building, and never print a software library default as a result. Print each issued incident energy value next to its working distance. When the model run has not been issued, the write-up follows the worked summary: it lists the inputs, states that no sourced value exists yet, prints no incident energy, and holds the equipment labels. That is a complete statement of the state of the work, and it is the shape a draft study should have.
13. Build equipment labels only from issued results, and state the review clock. Each label carries the fields the labelling rule in the adopted NFPA 70E edition asks for on gear such as switchboards, panelboards, industrial control panels, meter socket enclosures, and motor control centers that are likely to be worked on energized: nominal system voltage, arc flash boundary, and at least one of the available incident energy with its corresponding working distance, the arc flash PPE category for the equipment, the minimum arc rating of clothing, or the site specific level of PPE. NFPA 70E 130.5 asks that the arc flash risk assessment be reviewed for accuracy at intervals not exceeding five years and when a major modification or renovation occurs. Print the issue date, the review date, and the earlier triggers on the face of the study: a new service transformer, an added feeder, a utility change that moves available fault current, and any protective device or setting change.
14. Write a design report or basis of design in the same discipline. Open with criteria, editions, utility information and its date, and load inputs with their sources. Keep decisions and results in separate paragraphs: a decision names who decided, when, and on what, and a result names the calculation, its inputs, and its output. Give each system the same section shape: what it serves, how it was sized, the governing calculation, the result, and the open items. Close with an assumptions and open items list that matches the tracing sheet assumption rows one for one. If the two lists differ, one of them is wrong, and the report does not issue until they match.
15. Run the trace checker on the final version of every document, and treat its exit code as a block. Run python3 scripts/trace_check.py assets/value-tracing-sheet.csv --report <document> on each check copy, where every load bearing value carries its tracing id in brackets. The checker validates the sheet, counts assumptions in the open, fails on a marker with no row, and fails with exit code 2 on any number carrying a unit with no marker on its line. The three worked assets pass with 38 rows, 1 assumption, and 0 errors. A report line carrying an untraced 999 A value and a line citing a marker T-999 that does not exist both fail with code 2, as they should. Fix a failure by finding the source, or by marking the value as an assumption with its basis. Never fix it by deleting the value's unit, spelling the number out to dodge the check, or removing the checker from the workflow. The issued copy may drop the brackets. The sheet, the checker output, and the calculation output stay in the project file.

Output Contract

• Value tracing sheet: CSV with one row per load bearing value, with id, value, unit, report location, source type, and source detail, plus assumption rows that state their basis and closing event.
• Specification section: MasterFormat number and title from the project manual, in three part SectionFormat, with submittals that include the calculation package with its tracing sheet, only the ratings the design relies on in Part 2, and the field duties that protect the calculations in Part 3.
• Load report: connected, demand, and sizing loads listed and labelled separately, noncoincident loads shown with the one taken and the one left out, demand and sizing currents labelled, ampacity basis stated or flagged, and voltage drop shown for each conductor tried against the project criterion.
• Short circuit write-up: basis stated first, contributions listed with nameplate sources, per bus results table matching the drawing bus names, and a bus by bus interrupting and withstand check with any failure stated as a finding.
• Coordination write-up: per path curve references on a common voltage base, separation read at maximum and minimum fault current, settings tied to their curve files, protection and selectivity trade offs stated in plain words, uncoordinated paths listed as findings, and the field read back step named.
• Arc flash write-up: the 1584 edition named with scope confirmed, model inputs traced to their sheets, incident energy values printed with their working distances or held with the reason stated, labels built from issued results, and the review date and change triggers printed on the face of the study.
• Design report: basis of design first, decisions and results in separate paragraphs, one section per system in a fixed shape, and a closing assumptions list that matches the tracing sheet one for one.
• Checker output: the trace checker result for the final version of each document, with zero errors, or the unresolved values flagged in the issued document itself.

Operating Rules

• No number without a source. Every load bearing value traces to a calculation run on file, a code or standard table in the adopted edition, a nameplate, a field measure, a schedule, manufacturer data, a utility letter, or a dated quote. A figure from memory, from a prior project, or from a software default is a flag, not a value.
• Assumptions stay visible and owned. Each one carries a basis, an owner, and the event that closes it, and it prints on the face of the draft it affects. A document with an open assumption row does not call itself final.
• Editions are read, not remembered. Demand factors, unit loads, ampacities, conductor areas, and labelling fields come from the editions named in the project criteria. Where this skill names a code section or a recommended limit, verify it in the adopted edition before issuing, because numbering and values move between editions.
• Demand, connected, and sizing values never swap jobs. Voltage drop runs on operating current, ampacity checks run on sizing current, and a report labels which one it is using in every paragraph that uses one.
• Never sharpen a rough input. A route paced off as about a given length stays about that length or carries an assumption row. Lengths, impedances, and fault values do not gain precision between the field note and the report.
• A pass states its basis. Any check that passes on an assumption, an infinite bus basis, a preliminary utility value, or a pre construction route length says so in the same paragraph as the pass.
• Software output is an input, not a conclusion. The write-up states the model inputs, the edition, and the limits, and the engineer in responsible charge reviews the result. A study summary that cannot name its inputs cannot defend its outputs.
• Drafts stay marked as drafts. Non final documents carry the marking the state rule and firm practice require, labels are not issued from draft results, and no document is sealed by anyone other than the engineer in responsible charge of that work.