ICD authors usually write for fellow engineers, not parsers. That is sensible for a specification meant for people to read, but it can yield documents that are clear to humans and unreliable in automated processing. These five patterns occur most often in our work, and each creates a predictable code-generation failure.
1. Merged Cells and Color Groups Without Explicit Headers
Excel ICDs often merge cells to place related fields beneath one visual heading. For example, a packet section may use one merged cell across five rows labeled "Housekeeping Fields," while each row defines a separate field. People read this grouping easily. A parser sees one cell with a span and blank neighboring values. If it processes rows individually, the label exists only on the first row, leaving the other four without a section identifier.
The result is incomplete extraction: the first field is captured, while the other four may be discarded or assigned to another packet type. Add a packet-name or section-identifier column to every row, even when that repeats the same text 30 times. Repetition is preferable to unreliable downstream tooling.
2. Parent-Relative Bit-Field Offsets
Some ICDs, especially those defining packed sub-byte structures, state offsets from a named parent field instead of from the packet or application data field start. A field may read "bits 3 to 5 of the Mode Status byte" rather than "bits 19 to 21 from the start of the application data field."
To use a relative offset, the parser must first resolve the parent's absolute offset, then calculate the child's position. That works technically, but requires resolution state across rows. If the parent appears after its child rows, as in formats listing an aggregate field before its sub-fields only in a brief description, the calculation fails because the parent offset is still unknown.
Give every field a consistent absolute offset from one fixed reference point. This adds detail but removes ambiguity. Put human-oriented sub-field explanations in a separate "Notes" column instead of using them as the primary offset reference.
3. Mixed Endianness Without a Global Byte-Order Declaration
Correct decoding of multi-byte fields depends on byte order. CCSDS Space Packet Protocol uses big-endian order for header fields, while mission ICDs may specify little-endian payload fields to match a sensor or processor. Mixing the two is valid, but automated generation requires each field to declare its byte order explicitly.
The danger is silent encoding corruption. If a generator adopts the byte order of its first field as global, later fields using another convention are encoded incorrectly. The byte stream still parses, but its values are wrong. This is worse than a parse failure: test stubs generated from the same ICD will also be wrong, so encoder and test agree with each other while both disagree with the real field value.
Add a byte-order column or attribute to every multi-byte field. Do not depend on a header note a parser might miss or misread.
4. Conditional Fields Hidden in Prose Footnotes
Some packet fields exist only under specified conditions. A flag byte may appear only when a header bit is set, or a variable data block may follow the fixed header only when a length field is non-zero. These rules matter to code and test generation: the encoder must apply the condition, and tests must exercise both presence and absence.
Footnotes below the table hide these rules from a parser working through table rows. Generated code then emits the field every time, while tests omit the absent case. Sending such a field unconditionally may make a conformant receiver reject the packet because its length field no longer agrees with the content.
Add a conditional-presence column to the field table. Use a structured expression, or name the condition field and value. Parsers can implement structured conditions, but cannot reliably extract them from prose.
5. Version Tracking by Filename Only
This problem begins before parsing. If ICD history exists only in filenames such as ICD_AOCS_v3.xlsx, ICD_AOCS_v3_final.xlsx, and ICD_AOCS_v3_final_rev2.xlsx, with no version identifier inside the document, a generation tool cannot reliably tell which version it processed. The generated code therefore lacks a traceable document-version link.
After an ICD update is uploaded, the generator cannot identify changed fields without comparing the new parsed IR with the prior run's IR. If that earlier IR was not retained, or filenames followed no consistent convention, comparison cannot be performed.
Store a document version identifier in a fixed cell or internal field, not only in the filename. A version string in a dedicated field-table header row can be extracted and placed in generated code as a comment or constant, linking the artifact auditably to its source ICD version.
These Fixes Do Not Ensure Clean Parsing
Correcting these five patterns removes the most frequent automated ICD-processing failures, but does not eliminate manual review. Documents developed over years by multiple authors, documents combining fields from different standards, and documents using program-specific notation can still require human judgment somewhere in the parsing pipeline. The aim is to reduce manual intervention, not remove human review altogether. A tool claiming fully automatic processing without qualification is reporting an average based on clean inputs.
